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

Datei:HotkeySetupDialog.png

2018-07-06T07:26:16Z

Ab: Ab lud eine neue Version von „Datei:HotkeySetupDialog.png“ hoch

Settings HotKeySettings/en

2018-07-06T07:23:26Z

Ab:

== Hotkey Settings ==
The purpose of hotkeys is to allow some control over expecco, while recording a GUI interaction, without having to move the mouse or click on something (i.e. to avoid both interacting with the application and recording that interaction). Hotkeys are caught by expecco before they are sent to any application. Thus, any key which is defined as hotkey can NOT be sent to ANY window.

The Hotkey service is currently available only for Windows operating systems. The support for other operating systems is part of the roadmap and will be integrated in a future expecco release.

=== Available Hotkey Functions ===
In this version expecco supports the following hot key functions:

*Start a testrun in expecco (the hot key will be delegated to the last active browser window)
*Stop a running test execution
*Toggle (start/stop) the recording mode in expecco GUIBrowser
*Toggle (start/stop) the follow mouse mode in expecco GUIBrowser
*Get current focused UI element from application under test and select this element in the GUIBrowser tree
*Get current UI element under pointer from application under test and select this element in the GUIBrowser tree

The state of the hotkey service (running/stopped) is shown in the setting dialog.

=== Hotkey Setup ===
In the hotkey setup dialog you can specify the hotkeys you want to use within expecco. The default setting for the hotkeys is disabled. In the table (see image below) you can enable/disable each hotkey specification row by a check toggle. If disabled (check toggle is off), the hotkey will not be activated if the service is started. In the Hotkey and Modifier columns you can defined the keys you want to assign to the hotkey function.

The hotkey settings can not be changed while the service is running.

[[Datei:HotkeySetupDialog.png]]

If you want to start the hotkey service directly after the expecco startup, please enable the check box "Auto start hot key event listener". If you want to start the hotkey service manually press the "Start" button. If the "Start" button is disabled you may have unapplied changes in the settings. Please apply them first. After that the "Start" button should be enabled and ready for starting the service.

[[Category:Settings]]

Release Notes 2.x

2018-06-19T10:19:36Z

Ab:

see also: [[Release Notes 1.x]]

== Release 18.1 [previously planned as "2.12"] (Spring 2018) ==
With this release, we will start a new naming scheme,
using the publishing year as major version number and the delivery within the year as minor vsn.
 Thus, this version will be named "18.1.0.x".

This is a major new release with many [[Release18_1_UI_Enhancements | UI enhancements]], and a number of new features.

* Fix: attachment handling when moving items across projects (into/out of imported projects)
* Fix: occasional loosing SIGCHILD when multiple shell/cmd scripts were executed in parallel (race condition)
* Fix: many fixes for bugs/inconveniences reported by customers in expeccoALM
* Fix: STDLIB: "Stream [ read through]" was broken
* Fix: STDLIB: "Collection [ copyFromTo ]" and "Collection [ all but Last]" did not always raise an error.

* Feature: Java bridge, .Net bridge and Manual test are now part of the expecco base package and therefore included in the base installer

* Feature: many GUIBrowser enhancements
* Feature: FileBrowser: dump can be changed to be hex, octal, decimal or binary; character decoding in EBCDIC or 7-bit ASCII (to ignore high/parity bit)
* Feature: FileBrowser: search pattern can be entered as hex byte sequence
* Feature: [[Settings UpdatesSettings/en#Expecco_as_a_Patches_Server_.282.12.29|Patches server]]: one expecco may deliver patches to all other installations in the local network
* Feature: script actions are now executed inside the attachment folder by default. This makes it easier for the script to access files containing test data or configuration files. However, this is somewhat incompatible with previous versions, so this can be disabled via a settings flag. It can also be changed by providing the execution folder at the "''execDir''" pin.
* Feature: can pass [[ElementaryBlock Element/en#Environment_.28Shell-.29_Variables|shell environment variables to shell, batch actions]] (and all derived actions, like Ruby, Node.js, etc.)
* Feature: [[ElementaryBlock Element/en#Script_Expansion | script expansion]] with pin-value strings for shell, batch actions and all derived actions, like Ruby, Node.js, etc.
* Feature: [[ElementaryBlock Element/en#Matching_stdin.2Fstderr_against_a_Pattern|prompt matching in shell, batch actions]] (and all derived actions, like Ruby, Node.js, etc.)
* Feature: better error diagnostics (and error-line highlighting) in shell actions (and most derived actions, like Ruby, Node.js, etc.)
* Feature: [[DiagramElements-Pin/en#Do_not_Log_Pin-Value_in_Activitylog_Attribute|individual control over pin-value in activity log]] (e.g. to suppress passwords, cryptokeys etc.)
* Feature: [[DiagramElements-Pin/en#Output_Pin_Value_Timestamped_Attribute|output pin values can be individually timestamped]] (via step's pin menu)
* Feature: [[ElementaryBlock Element/en#Node.js-Script_Blocks|'''Node.js script blocks''']] and [[ElementaryBlock Element/en#Node.js_Blocks|'''Node.js elementary action blocks''']]
* Feature: [[VNC Plugin Reference/en|VNC GUI Testing plugin]]

* Feature: additional call API to invoke actions from elementary code (see [[Expecco_API/en#Execution | Expecco_API -> Execution]])
* Feature: "''Interrupt & Debug''" button in the [[Test Editor/en|Test-Runner]] (to interrupt runaway elementary blocks)
* Feature: New libraries for [[MQTT/en | MQTT (IoT)]] and [[SomeIP/en | Some/IP (Automotive)]] (licensed addons)
* Feature: [[Settings_DebuggerSettings/en#Freeze_Values_are_Immutable | Immutable FreezeValues]]
* Feature: New [[Plot/Graph Action Blocks | '''Plot/Graph action blocks''']]
* Feature: New [[R Action Blocks | '''R action blocks''']]
* Feature: New [[ElementaryBlock_Element/en#Python_Script_Blocks|Python Action Blocks]], [[ElementaryBlock_Element/en#Ruby_Script_Blocks|Ruby Action Blocks]], Perl Action Blocks, [[ElementaryBlock_Element/en#Node.js-Script_Blocks|Node Action Blocks]], Go Action Blocks and TCL Action Blocks
* Feature / UI enhancement: screenshot dialog includes an "Attach" button.
* Feature / UI enhancement: embedded XML inspector in the attachment editor
* Feature / UI enhancement: "Generate" submenu to generate XPath accessors in the attachment editor, when showing XML.
* Feature: New library (StatisticDistributionsLibrary.ets) to generate random numbers with various distributions for statistic/monte carlo/simulations
* Feature: New library (Plot_Graph.ets) to demonstrate the new Plot/Graph actions
* Feature: New [[DiagramElements-Probe | probe types ]] to record values without checks (especially useful for plot/graph generation)
* Feature: timestamps can now have sub-millisecond resolution
* Feature: [[Selenium_WebDriver_Plugin|Selenium WebDriver Plugin]]

* Feature Qt enhancement: Inject support for 32/64bit applications including pre build clients
* Feature Qt enhancement: Add support for accessing complex properties like images, colors, ...
* Feature Qt enhancement: Menu item / Menu action support in GUI Browser
* Feature Qt enhancement: Extention of the qt block library
* Feature Qt enhancement: Replace QtScript with Qt JS api for Qt5 clients
* Feature Qt enhancement: Introduce a hook for customer client extension

* Feature Manual test plugin: New java based excel import
* Feature Manual Test plugin: Complete rework of the wizard
* Feature Manual test plugin: New manual test block library

* Performance: Speed improvement in testplan execution

* UI Enhancement: script actions are now initially created with a minimum set of special pins (actually: only the stdout pin is created initially). More pins can be added (and unused pins can be removed) in the schema editor via the "Special Pins" menu. We found that the vast majority of script steps only needed that single pin, and that diagrams look nicer without them (you can change this to the old behaviour via "''Settings''" - "''Look & Feel''" - "''Diagram Editor''" - "''Create all Special Pins Initially''").
* UI Enhancement: coloring by type is now on by default (if you don't like it, go to "''Settings''"-"''Look & Feel''"-"''Diagram Editor''"-"''Look-Elements''" and turn it off again)
* UI Enhancement: Limit the number of levels in follow activity
* UI Enhancement: ActivityTree shows activities with handled exceptions in orange (used to be red). Also, the handling activity shows where the handled exception was thrown. Finally, the automatic navigation to the first error (after a run) will skip over handled exceptions, to place you immediately to the activity which was responsible for the failure or error.
* UI Enhancement: goto "recently modified" and "recently executed" menus in the main-menu
* UI Enhancement: "''Select Step in Diagram''" menu-function in the activity log tree viewer
* UI Enhancement: "''Exchange Connections''" menu-function in the network editor
* UI Enhancement: "''Import Attachments''" tools menu-function (to import many files)
* UI Enhancement: more information and functions in the Diff-viewer; new menu item in the "''Extra''"-menu: "''Compare two Testsuite Files''"
* UI Enhancement: "''Add/Remove Tag''" menu functions (in tree) can also be applied recursively to children of the selected item
* UI Enhancement: if a step was selected when a new step is created (by the "''New Step''" function or by paste), the new step is automatically connected via trigger-out/trigger-in
* UI Enhancement: Connect multiple (same-named) pins
* UI Enhancement: fix (rewrite) JavaScript elementary code, when a pin is renamed
* UI Enhancement: rewrite script code when a pin is renamed
* STD-LIB: New action blocks: Stream[Set Binary Mode], Stream[Set Text Mode], Stream[Set Error-at-End Mode]
* STD-LIB: New action blocks to access and query [[DiagramElements-Probe | probes]] by ID (in Misc/Probes)
* STD-LIB: New logInconclusive and logError actions (similar to logFailure, these mark the test's outcome, but continue execution)
* STD-LIB: New actions to configure HTTPS for tls1.2 / tls1.1 (some sites no longer accept tls1.1)

== Release 2.11.1 (Fall 2017) ==
* Bugfix Release including all patches for Release 2.11
* Fix: Windows Automation - Stability
* Fix: Problems with OLE

== Release 2.11 (Spring 2017) ==
* Fix: JSON parameter save/reload fixed
* Fix: method name check in codeView was disabled
* Feature: "must be executed" attribute in action definition
* Feature: extensions to the expecco GUI automation framework
* Feature: new interfaces for automotive and mechanical engineering technoligies
* Feature: new host bound single user licensing scheme

* Packaging: new expecco product bundle: "expecco Testcenter" - test automation plus test and resource management in one package

== Release 2.10.1 (= 2.10 + Patches) ==
* Fix: keyboard focus for menu
* Backward Compatibility Fix: the fixes in the JavaScript "indexOf()"-functions (done in 2.8) lead to problems with a customer (which migrated from 2.7.5 to 2.10). For this, two flags have been added to the suite-attributes, which enforce the old behavior for individual and/or all imported libraries. This allows for old code (which expects the wrong 1-based indexOf return values) to coexist with new code (which expects the correct 0-based versions) within a single test suite.

* Feature: [[Settings UpdatesSettings/en|Patches can be loaded via HTTP]] (FTP was blocked in some customers' networks)
* Performance: Bulk data transfers to network drives under Windows.

== Release 2.10 (Fall 2016) ==
* Feature: Mobile Testing Plugin (renamed from "''Appium Plugin''") got more support functions to administer appium & adb connections
* Feature: new "Reimport Tool" for bulk reimport and library (dependency) checking
* Feature: DLL-mapping dialog in the settings. For a typical usage example, see [[AutoIt Library#Installation|Installation of AutoIt]]
* Feature: New blocks in the stdlib ("''Split by Size''" and "''Split by Element''"), to split collections (strings) into sized pieces or at a separator.
* Feature: New command line options to specify individual parameter values
* Feature: More formats supported for external parameter files (JSON)
* Feature: new [[Starting expecco via Command Line/en#Detailed_Option_Description|command line]] arguments: -E, -P:, --parameter:, --silent, --licenseServerHost, --licenseServerPort
* Feature: the new [[Java Interface Library v2|Java Bridge V2]]/DotNET Bridge V2 is now used by the default. The new bridge uses only a single port for communication (thus making firewall/router setup easier), supports casts, better controllable argument-type specification, is faster in its communication and supports asynchronous messages with lazy results. In case of backward compatibility problems, the old bridge is still available and can be used by changing the settings.
* Feature: custom print length of the pin and log values for the report
* Feature: [[CompoundBlock Editor-CompoundWorksheet Editor/en#Controlling_Logging_and_Tracing|"''Ignore All Skip in Trace''"]] settings to enforce a full trace (for debugging)

* Performance: (dramatic) speedup in some image handling functions.
* Performance: speedup (50%) in the XML reader.
* Performance: speedup initial startup by not loading unlicensed plugins

* UI enhancement: GUI Browser: double click on action/attribute item adds it to the list
* UI enhancement: GUI Browser: reconnect/fix autostart when deleting recorded steps
* UI enhancement: GUI Browser: better undo handling
* UI enhancement: GUI Browser: keep tree and selection on refresh (not all technologies)
* UI enhancement: better replace-step dialog in diagram editor (library filter added)
* UI enhancement: Line numbers in the attachment editor
* UI enhancement: Line numbers and trim-blank-lines option in multiline freeze value entry
* UI enhancement: color settings for red-green deficiency (in status color dialog)

* Change: SerialPort Plugin: the port parameter pins (baudrate, stop-bits, parity etc.) are now parameter pins. This will only affect you, if the open-serial-port block is triggered via one of those pins (which is very very unlikely)

* Fix: All leftover (unclosed) external connections (Sockets, Serial Lines, Bridges) are closed after a testrun, when in slave mode
* Fix: All leftover (unterminated) started appium servers are closed after a testrun, when in slave mode
* Fix: Multiline freeze value editor interpreted strings starting with digits as numeric value
* Fix: Multiline freeze value editor allows for empty lines at the end

== Release 2.9 (June/2016) ==
* Feature: Mobile Testing (aka "Appium")-Plugin: Add recorder
* Feature: Mobile Testing Plugin: Update capabilities
* Feature: Mobile Testing Plugin: Settings Dialog for setting up external auxiliary programs (adb, Appium Server, AVD Manager, SDK Manager)
* Feature: Mobile Testing Plugin: New menu for launching auxiliary programs (Appium Server, AVD Manager, SDK Manager)
* Feature: Mobile Testing Plugin: New buttons in Android Wizard to refresh the device list, launch AVD Manager, install APKs.
* Feature: Mobile Testing Plugin: Save and load connection settings in and from attachments in test suite.
* Feature: Mobile Testing Plugin: Allow editing and copying of connection settings.
* Feature: Mobile Testing Plugin: Allow adding arbitrary capabilities for forward compatibility.
* Feature: Mobile Testing Plugin Bundle: Update contents, in particular use Appium Server 1.4.16.
* Feature: Mobile Testing Plugin Bundle: Remove Android emulator from bundle as it is huge. If needed, download and install it separately.
* Feature: [[Java Interface Library v2|New Java Bridge (still experimental in 2.9)]]. The old Java Bridge is still available and enabled by default.

* UI enhancement: Mobile Testing Plugin: More verbose warning dialogs.
* UI enhancement: Mobile Testing Plugin: Remove obsolete "Emulator Settings" from connection dialog (using the wizard is superior now).
* UI enhancement: Mobile Testing Plugin: Make newCommandTimeout capability user visible
* UI enhancement: Mobile Testing Plugin: Remove unimportantView from default capabilities
* UI enhancement: Mobile Testing Plugin: Automatically select entry in Android Wizard if only one is available.
* UI enhancement: Mobile Testing Plugin: Highlight unknown capabilities to give a hint in case of bad spelling.
* UI enhancement: Mobile Testing Plugin: Add a search filter for packages in the Android Wizard.
* UI enhancement: General/Linux: Support for Anti-Aliased XFT-Fonts.

* STD-LIB: Image Save block supports writing of JPEG images.
* Mobile Testing Library: New blocks for multi-touch actions
* Mobile Testing Library: New block for reading capabilities from files
* Mobile Testing Library: New blocks for reading logs
* Mobile Testing Library: New block "Find Elements by XPath" for finding sets of elements
* Mobile Testing Library: New blocks for consecutive actions on single elements
* Mobile Testing Library: New block for taking screenshots
* Mobile Testing Library: New blocks for pressKeyCode API, make old blocks (sendKeyEvent API) obsolete

* Localization: Mobile Testing Plugin: German translation mostly complete.
* Documentation: Update and add more documentation to Appium library.

* Fix: Mobile Testing Plugin: Timeout in Android Wizard if adb does not return.
* Fix: Mobile Testing Plugin: Do not cut off multi-line status messages in Android Wizard.
* Fix: Mobile Testing Plugin: Fix error and bad behavior when cancelling file dialog in connection settings.
* Fix: Mobile Testing Plugin: Do not drop connection settings on connection error.
* Fix: Mobile Testing Plugin: Use Java path from Settings
* Fix: XML/XPath - accepts underscore ('_') and Unicode characters in element and attribute names.
* Fix: RemoteAccess Plugin - fix error waiting for prompt
* Fix: RemoteAccess Plugin - fix response in same line as command
* Fix: Java GUI Plugin - fix error in "Verify Path"

== Release 2.8 (Q4/2015) ==
'''Notice: You have to install a patch for expecco 2.7.5, if you want to load a Testsuite which was edited in expecco 2.8 and uses some of the new features! [[release2.8 incompatibilities|(More info)]]'''

* Feature: [[TableDrivenBlock Element|Table driven actions]]; these offer a simpler, table oriented interface
* Feature: Mobile Testing-Plugin (was "Appium"-Plugin) for Android and Apple iOS test automation for mobile devices
* Feature: Variable number of pins in groups ([[DiagramElements-Pin/en#Variable_Number_of_Pins|"Variable Pin Groups"]])
* Feature: First release of the [[User Defined Menu Items#Useful_Building_Blocks_for_Custom_Menu_Operations|Expecco Reflection Library]] (to automate expecco itself)
* Feature: Enum datatype: support for individual assigned enum values, described in the [[Datatype Editor/en#Enumeration_Types|Datatype Editor Documentation]] and the [[Datatype Element/en#Enumeration_Types|Datatype Element Documentation]] and also the [[Expecco API/en#Enum Type Functions|API Documentation]].
* Feature: [[Starting expecco via Command Line#Expecco_REST_Service_Interface|REST service]] for remote controlling expecco execution
* Feature: New [[ElementaryBlock Element/en#Ruby_Script_Blocks|Ruby actions]]
* Feature: Better execution directory settings for [[ElementaryBlock Element/en#Shell_Script_Blocks|Shell blocks]]
* Feature: New step attributes for more specific [[CompoundBlock Editor-CompoundWorksheet Editor/en#Step_Specific_Options_.28Context_Menu.29|"skip in log/trace"]] options (for looping actions)
* Feature: New user preference setting to ignore all [[CompoundBlock Editor-CompoundWorksheet Editor/en#Step_Specific_Options_.28Context_Menu.29|skip-in-log]] attributes (for debugging)
* Feature: "immediate fork new process" flag now also in block description or dynamically from elementary code
* Feature: Improved performer data type handling; virtual steps now only accept valid performers, and freeze value choices are filtered for valid performers.
* Feature: Option to start background action before or after pre-action
* Feature: New constraint datatype type (for better freeze value selection)
* Feature/Fix: compatibility of indexOf() / lastIndexOf() JavaScript functions (allow substring search)
* Feature: Data inspector for strings shows another (XML-DOM) tab if the string is an XML string. This tab shows the parsed XML DOM-tree.
* Feature: Attachments can now be declared as binary file attachment. These will not be interpreted; especially, no cr/lf translation and utf8 or similar character translation is performed. Binary attachments are required, e.g. to embed jar or other code files.

* UI enhancement: Multiline labels in steps (use "\" as line-separator)
* UI enhancement: Additional custom headline and custom text block in reports (can be filled in right before printing).
* UI enhancement: Can now also set breakpoints on steps and code lines of readonly actions (e.g. in an imported library)
* UI enhancement: Undo gives a warning when about to undo past the previous file-save state
* UI enhancement: Added a menu item in "Extras" - "Debugging" to stop [[User Defined Menu Items#Asynchronous_.28Background.29_Actions|background menu actions]]
* UI enhancement: Added more convenient pin-comment editing support to the schema editor
* UI enhancement: Text editor has a new "split" menu function in its tools-submenu
* UI enhancement: Better "New Step" and "Replace Step" dialogs in the diagram editor (showing preview, code and contents; also show attachments).
* UI enhancement: Better autoconnect and matching blocks search algorithm in the "Place and Select New Step" function (i.e. New Step function, when an output pin is selected)
* UI enhancement: New scale diagram function (scale and spread multiple steps)
* UI enhancement: Lint performs a number of checks on a block being edited and gives immediate warnings in the info line (same checks as in the tree's error- and special search tabs)
* UI enhancement: New lint-error check rules to detect consumed pin values in loops and multi-triggered chains.
* UI enhancement: Double click on a search item to navigate to it in the tree
* UI enhancement: Codeview and network view in the activitylog indicate that they are readonly.
* UI enhancement: Secondary navigation tree for drag&drop.
* UI enhancement: Warn if it is due time to check for updates.

* STD-LIB: Collection creator and multi-setter blocks with variable number of pins (alternating key-value pairs)
* STD-LIB: New DLL-Mapping block
* STD-LIB: New blocks "File [modification time]", "File [access time]" and "File [creation time]".
* STD-LIB: Additional blocks for event queue handling.
* STD-LIB: Additional blocks for static step-local storage.
* STD-LIB: Better versions for FAIL/WARN/INFO, LogFAIL, logWARNING and logINFO. New "Transcriber with Timestamp" action.
* STD-LIB: Fixed some collection-type issues (now pins are #-template-typed, instead of Collection), which required a downcast in many suites.
* STD-LIB: New blocks: "Trigger Periodically" and "Counter"
* STD-LIB: New blocks: "Enumtype symbol<->integer"

* Fix: Freeze value menu of unions of enums did not merge the individual enum values
* Fix: Freeze value menu of unions of constraint dataType-types
* Fix: The search breakpoints function (in the errors-tab of the treeview) now also finds statement breakpoints.
* Fix: Fixes and improvements in the SOAP, REST and WSDL frameworks
* Fix: Enum numeric value assignments were lost sometimes when saving/restoring
* Fix: Search for references of a variable did not find them in imported libraries
* Fix: Report of looped testplans (pre-action was reported multiple times)
* Fix: behavior of cancel pin (did neither drive triggerOut-pin, nor exception-pin)
* Fix: Fixes for crashes in follow mouse and backward (XPath) compatibility in WindowsAutomation Plugin
* Fix: The embedded type editor for defined classes lost its code window, when reopened on another class type.
* Fix: Proper class naming is now enforced in the type editor.

== Release 2.7.5 (2015-06-09) ==
'''New features''':
* The JavaFX plugin now supports keyboard input. Use the block "''Request Focus''" to focus an input field and the block "''Type Text''" to enter any text.

'''Bugfixes''':
* The JavaFX plugin now provides improved connection handling.

For expecco running under Linux you need glibc >= 2.14

Tested technology versions:
* Selenium
* The Java Bridge requires a JDK version 1.6 or higher
* JavaFX testing requires JavaFX 8
* Qt: Qt 2.6.3 (MinGW, vs2008), Qt 4.8.4 (MinGW, vs2008, vs2010, vs2013), Qt 5.4.2 (vs2010, vs2013)
* .NET
* MFC
* HTML 5
* DevExpress
* Android
* iOS
* Windows CE/Mobile Phone
* CANoe: 8.2 SP4
* WSDL-Import: it is required that you re-import your WSDL-Definitions in your Testsuites

==Release 2.7.1 ==
* Convenient menu functions to add the special [[Expecco API#Using a Particular JVM Connection / Executing Groovy on a Possibly Remote Machine|"java" and "groovy"]] input pins to a Groovy elementary block.
* Standard library: new blocks: "''Directory [ Contents as Filenames ]''", "''Directory [ Contents as Pathnames ]''", "''Directory [ Contents as Basenames ]''", "''File [ isReadable? ]''" and "''File [ isWritable? ]''"

==Release 2.7 ==
* Patches go into a release specific directory (e.g. patches-2.7.0.5)
* configurable external editor for attachments and csv data (e.g. excel or openoffice calculator)
* tree view: markers in search lists; add to/remove from remembered list menu items
* tree view: folders can have tags, too
* tree view: per-tag icons in tree
* [[Starting expecco via Command Line/en#Utility_Functions|"--diff" command line option]]
* [[Starting expecco via Command Line/en#Startup|"--settings" command line option]]
* Scatter/Gather composition of test plans from multiple suites [[Starting expecco via Command Line/en#Scatter Gather Test Suite Composition|via command line arguments]]
* library: background OS process and background block actions
* improved type checks and preference settings
* schema editor: cursor up/down keys in pin name fields
* schema and diagram editor: additional menu functions in multiple-pin selection menu
* new blocks in the StandardLibrary: ExceptionClassifier, WriteCSV, Load/Save Environment from/to CSV
* [[SAP Testing|SAP plugin and VBScript action blocks]]
* change in the handling of Groovy callbacks. Please read [[Expecco API/en#Attention_.2F_Warning|"Attention / Warning"]] and [[Expecco API/en#Special_Functions|"Special Functions"]] in the Groovy API documentation.
* improved Groovy debugging support
* new common Android and iPhone/iPad testing framework
* option to save a per-run report, when a suite is executed in a loop (especially useful, when running until fail or until success)
* block assertions: assert-executed / assert-all outputs written / assert any output written
* License server support

==Release 2.6.2 bugfix release - April 2014 ==
Thus is a stable release consisting of the 2.6.1 base version INCLUDING all 2.6.1 patches (up to April).

==Release 2.6.1 update - January 2014 ==
* [[Expecco API#Groovy_Elementary_Blocks|groovy action]]: the java-bridge can be passed in via pin named "java" or environment var named "JAVA". GroovyShell can be passed in via pin named "groovy" or variable named "GROOVY". Pins are optional for backward compatibility.

==Release 2.6 - November 2013 ==
* New testplan execution loop mode: "loop until required test fails"
* More options for automatic check for and installation of updates & patches
* Better default directories in file open/save/import dialogs.
* Tuned automatic reimport when multiple libraries are imported.
* Improved Java object inspector
* New attachment contents representation modes.
* Step tooltips include the underlying block's tree location.
* Shift click on connection selects all underlying connections.
* Give an indication (colorize menubar) if running with root/Admin rights.
* Option to put the custom operations menu into the top menu
* Additional tab in tree view to search by item-type
* Additional search options for interfaces and concrete actions
* Various bug fixes & enhancements:
** handle duplicate attachment filenames,
** fixed some type conversions,
** fixed clipboard handling under XWindow/Qt desktop,
** fixed non-changing testplan/testitem spec page.
** added string search in resources, skills and inventories
** no longer close expanded tree items when reimporting
** fixed making an imported library writable, which is imported by another sub-import
** fixed freeze of template pin to boolean/enum
** fixed enum values which start with a digit (aka '001 aaa')
** remove freeze value connection via menu

==Release 2.5 ==
* Can refer to [[Environment Editor#Initialization Types|shell environment variables]] in an environment variable's initializer.
* New elementary block type: Groovy Code. Installs script code to be executed in a Java target or a local JVM.
* New keyword driven actions
* Additional checks in save dialogs to prevent overwriting another testsuite/library
* Optional automatic reimport or check for reimportable imports (configure via settings dialog)
* Additional freeze value validation when types are edited
* New plugin: Jar Import
* New and much improved manual test import plugin
* Speedup, improvements and fixes in the JavaBridge plugin
* Menu actions can [[Misc Editor#Background_Actions|execute in the background]] (name as "...&")
* Background actions in testplan and testcase
* Much faster: startup, plugin loading and bridge communication
* Multiple freeze value menu organizations for enum types (hierarchical selection)

===Release 2.5.1 - July 2013 ===

* Automatic & semiautomatic update from server

==Release 2.4 - February 2013 ==
This is a bugfix release, in which various patches and small enhancements from the past few months have been integrated.

==Release 2.3 - December 2012 ==
* New integrated GUI Browser
* New menu functions: "minimize/restore all Windows"
* Polarion compatible report
* Improved Project-Diff-Browser

==Release 2.2==
* New SchemaEditor menu functions: copy/paste pin interface
* New plugin: [[GembirdPowerControlPlugin Reference#|Gembird Power Control Plugin]]
* New debug-menu function: "close all temporary windows"
* [[Probe|Probes]]; easy recording and check of pinValues
* JUnit compatible report
* HTTP and SOAP transmission log (optional on Transcript)
* Fixed WSDL/SOAP for document-style operations
* Better inspector (hex dump tab, hex representation of floats)

==Release 2.1 - November 2011==
* Condition variables for simple (and easy to use) control of testcase execution
* [[Webservices#REST_Baustein|REST-Call]] blocks
* Option to disable logging of activityNotifications (from the underlying language framework)
* URL-override for SOAP service call blocks via the SOAP_URL environment variable.
* Access to the certificate store (for SSL/HTTPS), allows adding and removing individual certificates
* Elementary steps can have a variable number of output-pins (for multiplexer, dispatcher, round-robin generators etc.)
* New menu function: "Generate Value Extractor" for Dictionary-typed pin values. (in the activityLog, output pin-data menu)
* New tree-menu function: "Refactor"->"Change Variable Access", to search for and replace environment variable references.
* New datatype [[Datatype Element#Special_Types|"struct"]], to represent arbitrary compound (struct) values.
* GUI improvements: better annotation-text editors; line numbers, tags in file viewer
* Allow for multi pin-value parametrization in testplan (block with multiple inputs in a testplan item)
* Proxy support for HTTP-fetch blocks
* Recording feature for Java Swing GUIs
* Enhanced Java Swing Function Block Library
* GUI Browser improvements: tree view with widget specific icons, record tree actions

==Release 2.0==
* Elementary steps can have a variable number of input-pins (improves the format, plus, string-concat and many other blocks)
* Statistic page added to the project editor
* Improved manual test import plugin; nicer Manualtest runner GUI; user definable manual test GUI
* Allow for pin-value parametrization in testplan (block with a single input parameter in a testplan item)
* Configurable max. cleanup time after terminating a run; Confirmation Dialog when longer.
* ActivityLog: added "Select in Tree" from log-entry
* HTTPS / SSL Support for HTTP blocks

Release Notes 2.x

2018-06-19T10:18:37Z

Ab:

see also: [[Release Notes 1.x]]

== Release 18.1 [previously planned as "2.12"] (Spring 2018) ==
With this release, we will start a new naming scheme,
using the publishing year as major version number and the delivery within the year as minor vsn.
 Thus, this version will be named "18.1.0.x".

This is a major new release with many [[Release18_1_UI_Enhancements | UI enhancements]], and a number of new features.

* Fix: attachment handling when moving items across projects (into/out of imported projects)
* Fix: occasional loosing SIGCHILD when multiple shell/cmd scripts were executed in parallel (race condition)
* Fix: many fixes for bugs/inconveniences reported by customers in expeccoALM
* Fix: STDLIB: "Stream [ read through]" was broken
* Fix: STDLIB: "Collection [ copyFromTo ]" and "Collection [ all but Last]" did not always raise an error.

* Feature: Java bridge, .Net bridge and Manual test are now part of the expecco base package and therefore now included in the base installer

* Feature: many GUIBrowser enhancements
* Feature: FileBrowser: dump can be changed to be hex, octal, decimal or binary; character decoding in EBCDIC or 7-bit ASCII (to ignore high/parity bit)
* Feature: FileBrowser: search pattern can be entered as hex byte sequence
* Feature: [[Settings UpdatesSettings/en#Expecco_as_a_Patches_Server_.282.12.29|Patches server]]: one expecco may deliver patches to all other installations in the local network
* Feature: script actions are now executed inside the attachment folder by default. This makes it easier for the script to access files containing test data or configuration files. However, this is somewhat incompatible with previous versions, so this can be disabled via a settings flag. It can also be changed by providing the execution folder at the "''execDir''" pin.
* Feature: can pass [[ElementaryBlock Element/en#Environment_.28Shell-.29_Variables|shell environment variables to shell, batch actions]] (and all derived actions, like Ruby, Node.js, etc.)
* Feature: [[ElementaryBlock Element/en#Script_Expansion | script expansion]] with pin-value strings for shell, batch actions and all derived actions, like Ruby, Node.js, etc.
* Feature: [[ElementaryBlock Element/en#Matching_stdin.2Fstderr_against_a_Pattern|prompt matching in shell, batch actions]] (and all derived actions, like Ruby, Node.js, etc.)
* Feature: better error diagnostics (and error-line highlighting) in shell actions (and most derived actions, like Ruby, Node.js, etc.)
* Feature: [[DiagramElements-Pin/en#Do_not_Log_Pin-Value_in_Activitylog_Attribute|individual control over pin-value in activity log]] (e.g. to suppress passwords, cryptokeys etc.)
* Feature: [[DiagramElements-Pin/en#Output_Pin_Value_Timestamped_Attribute|output pin values can be individually timestamped]] (via step's pin menu)
* Feature: [[ElementaryBlock Element/en#Node.js-Script_Blocks|'''Node.js script blocks''']] and [[ElementaryBlock Element/en#Node.js_Blocks|'''Node.js elementary action blocks''']]
* Feature: [[VNC Plugin Reference/en|VNC GUI Testing plugin]]

* Feature: additional call API to invoke actions from elementary code (see [[Expecco_API/en#Execution | Expecco_API -> Execution]])
* Feature: "''Interrupt & Debug''" button in the [[Test Editor/en|Test-Runner]] (to interrupt runaway elementary blocks)
* Feature: New libraries for [[MQTT/en | MQTT (IoT)]] and [[SomeIP/en | Some/IP (Automotive)]] (licensed addons)
* Feature: [[Settings_DebuggerSettings/en#Freeze_Values_are_Immutable | Immutable FreezeValues]]
* Feature: New [[Plot/Graph Action Blocks | '''Plot/Graph action blocks''']]
* Feature: New [[R Action Blocks | '''R action blocks''']]
* Feature: New [[ElementaryBlock_Element/en#Python_Script_Blocks|Python Action Blocks]], [[ElementaryBlock_Element/en#Ruby_Script_Blocks|Ruby Action Blocks]], Perl Action Blocks, [[ElementaryBlock_Element/en#Node.js-Script_Blocks|Node Action Blocks]], Go Action Blocks and TCL Action Blocks
* Feature / UI enhancement: screenshot dialog includes an "Attach" button.
* Feature / UI enhancement: embedded XML inspector in the attachment editor
* Feature / UI enhancement: "Generate" submenu to generate XPath accessors in the attachment editor, when showing XML.
* Feature: New library (StatisticDistributionsLibrary.ets) to generate random numbers with various distributions for statistic/monte carlo/simulations
* Feature: New library (Plot_Graph.ets) to demonstrate the new Plot/Graph actions
* Feature: New [[DiagramElements-Probe | probe types ]] to record values without checks (especially useful for plot/graph generation)
* Feature: timestamps can now have sub-millisecond resolution
* Feature: [[Selenium_WebDriver_Plugin|Selenium WebDriver Plugin]]

* Feature Qt enhancement: Inject support for 32/64bit applications including pre build clients
* Feature Qt enhancement: Add support for accessing complex properties like images, colors, ...
* Feature Qt enhancement: Menu item / Menu action support in GUI Browser
* Feature Qt enhancement: Extention of the qt block library
* Feature Qt enhancement: Replace QtScript with Qt JS api for Qt5 clients
* Feature Qt enhancement: Introduce a hook for customer client extension

* Feature Manual test plugin: New java based excel import
* Feature Manual Test plugin: Complete rework of the wizard
* Feature Manual test plugin: New manual test block library

* Performance: Speed improvement in testplan execution

* UI Enhancement: script actions are now initially created with a minimum set of special pins (actually: only the stdout pin is created initially). More pins can be added (and unused pins can be removed) in the schema editor via the "Special Pins" menu. We found that the vast majority of script steps only needed that single pin, and that diagrams look nicer without them (you can change this to the old behaviour via "''Settings''" - "''Look & Feel''" - "''Diagram Editor''" - "''Create all Special Pins Initially''").
* UI Enhancement: coloring by type is now on by default (if you don't like it, go to "''Settings''"-"''Look & Feel''"-"''Diagram Editor''"-"''Look-Elements''" and turn it off again)
* UI Enhancement: Limit the number of levels in follow activity
* UI Enhancement: ActivityTree shows activities with handled exceptions in orange (used to be red). Also, the handling activity shows where the handled exception was thrown. Finally, the automatic navigation to the first error (after a run) will skip over handled exceptions, to place you immediately to the activity which was responsible for the failure or error.
* UI Enhancement: goto "recently modified" and "recently executed" menus in the main-menu
* UI Enhancement: "''Select Step in Diagram''" menu-function in the activity log tree viewer
* UI Enhancement: "''Exchange Connections''" menu-function in the network editor
* UI Enhancement: "''Import Attachments''" tools menu-function (to import many files)
* UI Enhancement: more information and functions in the Diff-viewer; new menu item in the "''Extra''"-menu: "''Compare two Testsuite Files''"
* UI Enhancement: "''Add/Remove Tag''" menu functions (in tree) can also be applied recursively to children of the selected item
* UI Enhancement: if a step was selected when a new step is created (by the "''New Step''" function or by paste), the new step is automatically connected via trigger-out/trigger-in
* UI Enhancement: Connect multiple (same-named) pins
* UI Enhancement: fix (rewrite) JavaScript elementary code, when a pin is renamed
* UI Enhancement: rewrite script code when a pin is renamed
* STD-LIB: New action blocks: Stream[Set Binary Mode], Stream[Set Text Mode], Stream[Set Error-at-End Mode]
* STD-LIB: New action blocks to access and query [[DiagramElements-Probe | probes]] by ID (in Misc/Probes)
* STD-LIB: New logInconclusive and logError actions (similar to logFailure, these mark the test's outcome, but continue execution)
* STD-LIB: New actions to configure HTTPS for tls1.2 / tls1.1 (some sites no longer accept tls1.1)

== Release 2.11.1 (Fall 2017) ==
* Bugfix Release including all patches for Release 2.11
* Fix: Windows Automation - Stability
* Fix: Problems with OLE

== Release 2.11 (Spring 2017) ==
* Fix: JSON parameter save/reload fixed
* Fix: method name check in codeView was disabled
* Feature: "must be executed" attribute in action definition
* Feature: extensions to the expecco GUI automation framework
* Feature: new interfaces for automotive and mechanical engineering technoligies
* Feature: new host bound single user licensing scheme

* Packaging: new expecco product bundle: "expecco Testcenter" - test automation plus test and resource management in one package

== Release 2.10.1 (= 2.10 + Patches) ==
* Fix: keyboard focus for menu
* Backward Compatibility Fix: the fixes in the JavaScript "indexOf()"-functions (done in 2.8) lead to problems with a customer (which migrated from 2.7.5 to 2.10). For this, two flags have been added to the suite-attributes, which enforce the old behavior for individual and/or all imported libraries. This allows for old code (which expects the wrong 1-based indexOf return values) to coexist with new code (which expects the correct 0-based versions) within a single test suite.

* Feature: [[Settings UpdatesSettings/en|Patches can be loaded via HTTP]] (FTP was blocked in some customers' networks)
* Performance: Bulk data transfers to network drives under Windows.

== Release 2.10 (Fall 2016) ==
* Feature: Mobile Testing Plugin (renamed from "''Appium Plugin''") got more support functions to administer appium & adb connections
* Feature: new "Reimport Tool" for bulk reimport and library (dependency) checking
* Feature: DLL-mapping dialog in the settings. For a typical usage example, see [[AutoIt Library#Installation|Installation of AutoIt]]
* Feature: New blocks in the stdlib ("''Split by Size''" and "''Split by Element''"), to split collections (strings) into sized pieces or at a separator.
* Feature: New command line options to specify individual parameter values
* Feature: More formats supported for external parameter files (JSON)
* Feature: new [[Starting expecco via Command Line/en#Detailed_Option_Description|command line]] arguments: -E, -P:, --parameter:, --silent, --licenseServerHost, --licenseServerPort
* Feature: the new [[Java Interface Library v2|Java Bridge V2]]/DotNET Bridge V2 is now used by the default. The new bridge uses only a single port for communication (thus making firewall/router setup easier), supports casts, better controllable argument-type specification, is faster in its communication and supports asynchronous messages with lazy results. In case of backward compatibility problems, the old bridge is still available and can be used by changing the settings.
* Feature: custom print length of the pin and log values for the report
* Feature: [[CompoundBlock Editor-CompoundWorksheet Editor/en#Controlling_Logging_and_Tracing|"''Ignore All Skip in Trace''"]] settings to enforce a full trace (for debugging)

* Performance: (dramatic) speedup in some image handling functions.
* Performance: speedup (50%) in the XML reader.
* Performance: speedup initial startup by not loading unlicensed plugins

* UI enhancement: GUI Browser: double click on action/attribute item adds it to the list
* UI enhancement: GUI Browser: reconnect/fix autostart when deleting recorded steps
* UI enhancement: GUI Browser: better undo handling
* UI enhancement: GUI Browser: keep tree and selection on refresh (not all technologies)
* UI enhancement: better replace-step dialog in diagram editor (library filter added)
* UI enhancement: Line numbers in the attachment editor
* UI enhancement: Line numbers and trim-blank-lines option in multiline freeze value entry
* UI enhancement: color settings for red-green deficiency (in status color dialog)

* Change: SerialPort Plugin: the port parameter pins (baudrate, stop-bits, parity etc.) are now parameter pins. This will only affect you, if the open-serial-port block is triggered via one of those pins (which is very very unlikely)

* Fix: All leftover (unclosed) external connections (Sockets, Serial Lines, Bridges) are closed after a testrun, when in slave mode
* Fix: All leftover (unterminated) started appium servers are closed after a testrun, when in slave mode
* Fix: Multiline freeze value editor interpreted strings starting with digits as numeric value
* Fix: Multiline freeze value editor allows for empty lines at the end

== Release 2.9 (June/2016) ==
* Feature: Mobile Testing (aka "Appium")-Plugin: Add recorder
* Feature: Mobile Testing Plugin: Update capabilities
* Feature: Mobile Testing Plugin: Settings Dialog for setting up external auxiliary programs (adb, Appium Server, AVD Manager, SDK Manager)
* Feature: Mobile Testing Plugin: New menu for launching auxiliary programs (Appium Server, AVD Manager, SDK Manager)
* Feature: Mobile Testing Plugin: New buttons in Android Wizard to refresh the device list, launch AVD Manager, install APKs.
* Feature: Mobile Testing Plugin: Save and load connection settings in and from attachments in test suite.
* Feature: Mobile Testing Plugin: Allow editing and copying of connection settings.
* Feature: Mobile Testing Plugin: Allow adding arbitrary capabilities for forward compatibility.
* Feature: Mobile Testing Plugin Bundle: Update contents, in particular use Appium Server 1.4.16.
* Feature: Mobile Testing Plugin Bundle: Remove Android emulator from bundle as it is huge. If needed, download and install it separately.
* Feature: [[Java Interface Library v2|New Java Bridge (still experimental in 2.9)]]. The old Java Bridge is still available and enabled by default.

* UI enhancement: Mobile Testing Plugin: More verbose warning dialogs.
* UI enhancement: Mobile Testing Plugin: Remove obsolete "Emulator Settings" from connection dialog (using the wizard is superior now).
* UI enhancement: Mobile Testing Plugin: Make newCommandTimeout capability user visible
* UI enhancement: Mobile Testing Plugin: Remove unimportantView from default capabilities
* UI enhancement: Mobile Testing Plugin: Automatically select entry in Android Wizard if only one is available.
* UI enhancement: Mobile Testing Plugin: Highlight unknown capabilities to give a hint in case of bad spelling.
* UI enhancement: Mobile Testing Plugin: Add a search filter for packages in the Android Wizard.
* UI enhancement: General/Linux: Support for Anti-Aliased XFT-Fonts.

* STD-LIB: Image Save block supports writing of JPEG images.
* Mobile Testing Library: New blocks for multi-touch actions
* Mobile Testing Library: New block for reading capabilities from files
* Mobile Testing Library: New blocks for reading logs
* Mobile Testing Library: New block "Find Elements by XPath" for finding sets of elements
* Mobile Testing Library: New blocks for consecutive actions on single elements
* Mobile Testing Library: New block for taking screenshots
* Mobile Testing Library: New blocks for pressKeyCode API, make old blocks (sendKeyEvent API) obsolete

* Localization: Mobile Testing Plugin: German translation mostly complete.
* Documentation: Update and add more documentation to Appium library.

* Fix: Mobile Testing Plugin: Timeout in Android Wizard if adb does not return.
* Fix: Mobile Testing Plugin: Do not cut off multi-line status messages in Android Wizard.
* Fix: Mobile Testing Plugin: Fix error and bad behavior when cancelling file dialog in connection settings.
* Fix: Mobile Testing Plugin: Do not drop connection settings on connection error.
* Fix: Mobile Testing Plugin: Use Java path from Settings
* Fix: XML/XPath - accepts underscore ('_') and Unicode characters in element and attribute names.
* Fix: RemoteAccess Plugin - fix error waiting for prompt
* Fix: RemoteAccess Plugin - fix response in same line as command
* Fix: Java GUI Plugin - fix error in "Verify Path"

== Release 2.8 (Q4/2015) ==
'''Notice: You have to install a patch for expecco 2.7.5, if you want to load a Testsuite which was edited in expecco 2.8 and uses some of the new features! [[release2.8 incompatibilities|(More info)]]'''

* Feature: [[TableDrivenBlock Element|Table driven actions]]; these offer a simpler, table oriented interface
* Feature: Mobile Testing-Plugin (was "Appium"-Plugin) for Android and Apple iOS test automation for mobile devices
* Feature: Variable number of pins in groups ([[DiagramElements-Pin/en#Variable_Number_of_Pins|"Variable Pin Groups"]])
* Feature: First release of the [[User Defined Menu Items#Useful_Building_Blocks_for_Custom_Menu_Operations|Expecco Reflection Library]] (to automate expecco itself)
* Feature: Enum datatype: support for individual assigned enum values, described in the [[Datatype Editor/en#Enumeration_Types|Datatype Editor Documentation]] and the [[Datatype Element/en#Enumeration_Types|Datatype Element Documentation]] and also the [[Expecco API/en#Enum Type Functions|API Documentation]].
* Feature: [[Starting expecco via Command Line#Expecco_REST_Service_Interface|REST service]] for remote controlling expecco execution
* Feature: New [[ElementaryBlock Element/en#Ruby_Script_Blocks|Ruby actions]]
* Feature: Better execution directory settings for [[ElementaryBlock Element/en#Shell_Script_Blocks|Shell blocks]]
* Feature: New step attributes for more specific [[CompoundBlock Editor-CompoundWorksheet Editor/en#Step_Specific_Options_.28Context_Menu.29|"skip in log/trace"]] options (for looping actions)
* Feature: New user preference setting to ignore all [[CompoundBlock Editor-CompoundWorksheet Editor/en#Step_Specific_Options_.28Context_Menu.29|skip-in-log]] attributes (for debugging)
* Feature: "immediate fork new process" flag now also in block description or dynamically from elementary code
* Feature: Improved performer data type handling; virtual steps now only accept valid performers, and freeze value choices are filtered for valid performers.
* Feature: Option to start background action before or after pre-action
* Feature: New constraint datatype type (for better freeze value selection)
* Feature/Fix: compatibility of indexOf() / lastIndexOf() JavaScript functions (allow substring search)
* Feature: Data inspector for strings shows another (XML-DOM) tab if the string is an XML string. This tab shows the parsed XML DOM-tree.
* Feature: Attachments can now be declared as binary file attachment. These will not be interpreted; especially, no cr/lf translation and utf8 or similar character translation is performed. Binary attachments are required, e.g. to embed jar or other code files.

* UI enhancement: Multiline labels in steps (use "\" as line-separator)
* UI enhancement: Additional custom headline and custom text block in reports (can be filled in right before printing).
* UI enhancement: Can now also set breakpoints on steps and code lines of readonly actions (e.g. in an imported library)
* UI enhancement: Undo gives a warning when about to undo past the previous file-save state
* UI enhancement: Added a menu item in "Extras" - "Debugging" to stop [[User Defined Menu Items#Asynchronous_.28Background.29_Actions|background menu actions]]
* UI enhancement: Added more convenient pin-comment editing support to the schema editor
* UI enhancement: Text editor has a new "split" menu function in its tools-submenu
* UI enhancement: Better "New Step" and "Replace Step" dialogs in the diagram editor (showing preview, code and contents; also show attachments).
* UI enhancement: Better autoconnect and matching blocks search algorithm in the "Place and Select New Step" function (i.e. New Step function, when an output pin is selected)
* UI enhancement: New scale diagram function (scale and spread multiple steps)
* UI enhancement: Lint performs a number of checks on a block being edited and gives immediate warnings in the info line (same checks as in the tree's error- and special search tabs)
* UI enhancement: New lint-error check rules to detect consumed pin values in loops and multi-triggered chains.
* UI enhancement: Double click on a search item to navigate to it in the tree
* UI enhancement: Codeview and network view in the activitylog indicate that they are readonly.
* UI enhancement: Secondary navigation tree for drag&drop.
* UI enhancement: Warn if it is due time to check for updates.

* STD-LIB: Collection creator and multi-setter blocks with variable number of pins (alternating key-value pairs)
* STD-LIB: New DLL-Mapping block
* STD-LIB: New blocks "File [modification time]", "File [access time]" and "File [creation time]".
* STD-LIB: Additional blocks for event queue handling.
* STD-LIB: Additional blocks for static step-local storage.
* STD-LIB: Better versions for FAIL/WARN/INFO, LogFAIL, logWARNING and logINFO. New "Transcriber with Timestamp" action.
* STD-LIB: Fixed some collection-type issues (now pins are #-template-typed, instead of Collection), which required a downcast in many suites.
* STD-LIB: New blocks: "Trigger Periodically" and "Counter"
* STD-LIB: New blocks: "Enumtype symbol<->integer"

* Fix: Freeze value menu of unions of enums did not merge the individual enum values
* Fix: Freeze value menu of unions of constraint dataType-types
* Fix: The search breakpoints function (in the errors-tab of the treeview) now also finds statement breakpoints.
* Fix: Fixes and improvements in the SOAP, REST and WSDL frameworks
* Fix: Enum numeric value assignments were lost sometimes when saving/restoring
* Fix: Search for references of a variable did not find them in imported libraries
* Fix: Report of looped testplans (pre-action was reported multiple times)
* Fix: behavior of cancel pin (did neither drive triggerOut-pin, nor exception-pin)
* Fix: Fixes for crashes in follow mouse and backward (XPath) compatibility in WindowsAutomation Plugin
* Fix: The embedded type editor for defined classes lost its code window, when reopened on another class type.
* Fix: Proper class naming is now enforced in the type editor.

== Release 2.7.5 (2015-06-09) ==
'''New features''':
* The JavaFX plugin now supports keyboard input. Use the block "''Request Focus''" to focus an input field and the block "''Type Text''" to enter any text.

'''Bugfixes''':
* The JavaFX plugin now provides improved connection handling.

For expecco running under Linux you need glibc >= 2.14

Tested technology versions:
* Selenium
* The Java Bridge requires a JDK version 1.6 or higher
* JavaFX testing requires JavaFX 8
* Qt: Qt 2.6.3 (MinGW, vs2008), Qt 4.8.4 (MinGW, vs2008, vs2010, vs2013), Qt 5.4.2 (vs2010, vs2013)
* .NET
* MFC
* HTML 5
* DevExpress
* Android
* iOS
* Windows CE/Mobile Phone
* CANoe: 8.2 SP4
* WSDL-Import: it is required that you re-import your WSDL-Definitions in your Testsuites

==Release 2.7.1 ==
* Convenient menu functions to add the special [[Expecco API#Using a Particular JVM Connection / Executing Groovy on a Possibly Remote Machine|"java" and "groovy"]] input pins to a Groovy elementary block.
* Standard library: new blocks: "''Directory [ Contents as Filenames ]''", "''Directory [ Contents as Pathnames ]''", "''Directory [ Contents as Basenames ]''", "''File [ isReadable? ]''" and "''File [ isWritable? ]''"

==Release 2.7 ==
* Patches go into a release specific directory (e.g. patches-2.7.0.5)
* configurable external editor for attachments and csv data (e.g. excel or openoffice calculator)
* tree view: markers in search lists; add to/remove from remembered list menu items
* tree view: folders can have tags, too
* tree view: per-tag icons in tree
* [[Starting expecco via Command Line/en#Utility_Functions|"--diff" command line option]]
* [[Starting expecco via Command Line/en#Startup|"--settings" command line option]]
* Scatter/Gather composition of test plans from multiple suites [[Starting expecco via Command Line/en#Scatter Gather Test Suite Composition|via command line arguments]]
* library: background OS process and background block actions
* improved type checks and preference settings
* schema editor: cursor up/down keys in pin name fields
* schema and diagram editor: additional menu functions in multiple-pin selection menu
* new blocks in the StandardLibrary: ExceptionClassifier, WriteCSV, Load/Save Environment from/to CSV
* [[SAP Testing|SAP plugin and VBScript action blocks]]
* change in the handling of Groovy callbacks. Please read [[Expecco API/en#Attention_.2F_Warning|"Attention / Warning"]] and [[Expecco API/en#Special_Functions|"Special Functions"]] in the Groovy API documentation.
* improved Groovy debugging support
* new common Android and iPhone/iPad testing framework
* option to save a per-run report, when a suite is executed in a loop (especially useful, when running until fail or until success)
* block assertions: assert-executed / assert-all outputs written / assert any output written
* License server support

==Release 2.6.2 bugfix release - April 2014 ==
Thus is a stable release consisting of the 2.6.1 base version INCLUDING all 2.6.1 patches (up to April).

==Release 2.6.1 update - January 2014 ==
* [[Expecco API#Groovy_Elementary_Blocks|groovy action]]: the java-bridge can be passed in via pin named "java" or environment var named "JAVA". GroovyShell can be passed in via pin named "groovy" or variable named "GROOVY". Pins are optional for backward compatibility.

==Release 2.6 - November 2013 ==
* New testplan execution loop mode: "loop until required test fails"
* More options for automatic check for and installation of updates & patches
* Better default directories in file open/save/import dialogs.
* Tuned automatic reimport when multiple libraries are imported.
* Improved Java object inspector
* New attachment contents representation modes.
* Step tooltips include the underlying block's tree location.
* Shift click on connection selects all underlying connections.
* Give an indication (colorize menubar) if running with root/Admin rights.
* Option to put the custom operations menu into the top menu
* Additional tab in tree view to search by item-type
* Additional search options for interfaces and concrete actions
* Various bug fixes & enhancements:
** handle duplicate attachment filenames,
** fixed some type conversions,
** fixed clipboard handling under XWindow/Qt desktop,
** fixed non-changing testplan/testitem spec page.
** added string search in resources, skills and inventories
** no longer close expanded tree items when reimporting
** fixed making an imported library writable, which is imported by another sub-import
** fixed freeze of template pin to boolean/enum
** fixed enum values which start with a digit (aka '001 aaa')
** remove freeze value connection via menu

==Release 2.5 ==
* Can refer to [[Environment Editor#Initialization Types|shell environment variables]] in an environment variable's initializer.
* New elementary block type: Groovy Code. Installs script code to be executed in a Java target or a local JVM.
* New keyword driven actions
* Additional checks in save dialogs to prevent overwriting another testsuite/library
* Optional automatic reimport or check for reimportable imports (configure via settings dialog)
* Additional freeze value validation when types are edited
* New plugin: Jar Import
* New and much improved manual test import plugin
* Speedup, improvements and fixes in the JavaBridge plugin
* Menu actions can [[Misc Editor#Background_Actions|execute in the background]] (name as "...&")
* Background actions in testplan and testcase
* Much faster: startup, plugin loading and bridge communication
* Multiple freeze value menu organizations for enum types (hierarchical selection)

===Release 2.5.1 - July 2013 ===

* Automatic & semiautomatic update from server

==Release 2.4 - February 2013 ==
This is a bugfix release, in which various patches and small enhancements from the past few months have been integrated.

==Release 2.3 - December 2012 ==
* New integrated GUI Browser
* New menu functions: "minimize/restore all Windows"
* Polarion compatible report
* Improved Project-Diff-Browser

==Release 2.2==
* New SchemaEditor menu functions: copy/paste pin interface
* New plugin: [[GembirdPowerControlPlugin Reference#|Gembird Power Control Plugin]]
* New debug-menu function: "close all temporary windows"
* [[Probe|Probes]]; easy recording and check of pinValues
* JUnit compatible report
* HTTP and SOAP transmission log (optional on Transcript)
* Fixed WSDL/SOAP for document-style operations
* Better inspector (hex dump tab, hex representation of floats)

==Release 2.1 - November 2011==
* Condition variables for simple (and easy to use) control of testcase execution
* [[Webservices#REST_Baustein|REST-Call]] blocks
* Option to disable logging of activityNotifications (from the underlying language framework)
* URL-override for SOAP service call blocks via the SOAP_URL environment variable.
* Access to the certificate store (for SSL/HTTPS), allows adding and removing individual certificates
* Elementary steps can have a variable number of output-pins (for multiplexer, dispatcher, round-robin generators etc.)
* New menu function: "Generate Value Extractor" for Dictionary-typed pin values. (in the activityLog, output pin-data menu)
* New tree-menu function: "Refactor"->"Change Variable Access", to search for and replace environment variable references.
* New datatype [[Datatype Element#Special_Types|"struct"]], to represent arbitrary compound (struct) values.
* GUI improvements: better annotation-text editors; line numbers, tags in file viewer
* Allow for multi pin-value parametrization in testplan (block with multiple inputs in a testplan item)
* Proxy support for HTTP-fetch blocks
* Recording feature for Java Swing GUIs
* Enhanced Java Swing Function Block Library
* GUI Browser improvements: tree view with widget specific icons, record tree actions

==Release 2.0==
* Elementary steps can have a variable number of input-pins (improves the format, plus, string-concat and many other blocks)
* Statistic page added to the project editor
* Improved manual test import plugin; nicer Manualtest runner GUI; user definable manual test GUI
* Allow for pin-value parametrization in testplan (block with a single input parameter in a testplan item)
* Configurable max. cleanup time after terminating a run; Confirmation Dialog when longer.
* ActivityLog: added "Select in Tree" from log-entry
* HTTPS / SSL Support for HTTP blocks

Release Notes 2.x

2018-06-19T10:11:49Z

Ab:

see also: [[Release Notes 1.x]]

== Release 18.1 [previously planned as "2.12"] (Spring 2018) ==
With this release, we will start a new naming scheme,
using the publishing year as major version number and the delivery within the year as minor vsn.
 Thus, this version will be named "18.1.0.x".

This is a major new release with many [[Release18_1_UI_Enhancements | UI enhancements]], and a number of new features.

* Fix: attachment handling when moving items across projects (into/out of imported projects)
* Fix: occasional loosing SIGCHILD when multiple shell/cmd scripts were executed in parallel (race condition)
* Fix: many fixes for bugs/inconveniences reported by customers in expeccoALM
* Fix: STDLIB: "Stream [ read through]" was broken
* Fix: STDLIB: "Collection [ copyFromTo ]" and "Collection [ all but Last]" did not always raise an error.

* Feature: many GUIBrowser enhancements
* Feature: FileBrowser: dump can be changed to be hex, octal, decimal or binary; character decoding in EBCDIC or 7-bit ASCII (to ignore high/parity bit)
* Feature: FileBrowser: search pattern can be entered as hex byte sequence
* Feature: [[Settings UpdatesSettings/en#Expecco_as_a_Patches_Server_.282.12.29|Patches server]]: one expecco may deliver patches to all other installations in the local network
* Feature: script actions are now executed inside the attachment folder by default. This makes it easier for the script to access files containing test data or configuration files. However, this is somewhat incompatible with previous versions, so this can be disabled via a settings flag. It can also be changed by providing the execution folder at the "''execDir''" pin.
* Feature: can pass [[ElementaryBlock Element/en#Environment_.28Shell-.29_Variables|shell environment variables to shell, batch actions]] (and all derived actions, like Ruby, Node.js, etc.)
* Feature: [[ElementaryBlock Element/en#Script_Expansion | script expansion]] with pin-value strings for shell, batch actions and all derived actions, like Ruby, Node.js, etc.
* Feature: [[ElementaryBlock Element/en#Matching_stdin.2Fstderr_against_a_Pattern|prompt matching in shell, batch actions]] (and all derived actions, like Ruby, Node.js, etc.)
* Feature: better error diagnostics (and error-line highlighting) in shell actions (and most derived actions, like Ruby, Node.js, etc.)
* Feature: [[DiagramElements-Pin/en#Do_not_Log_Pin-Value_in_Activitylog_Attribute|individual control over pin-value in activity log]] (e.g. to suppress passwords, cryptokeys etc.)
* Feature: [[DiagramElements-Pin/en#Output_Pin_Value_Timestamped_Attribute|output pin values can be individually timestamped]] (via step's pin menu)
* Feature: [[ElementaryBlock Element/en#Node.js-Script_Blocks|'''Node.js script blocks''']] and [[ElementaryBlock Element/en#Node.js_Blocks|'''Node.js elementary action blocks''']]
* Feature: [[VNC Plugin Reference/en|VNC GUI Testing plugin]]

* Feature: additional call API to invoke actions from elementary code (see [[Expecco_API/en#Execution | Expecco_API -> Execution]])
* Feature: "''Interrupt & Debug''" button in the [[Test Editor/en|Test-Runner]] (to interrupt runaway elementary blocks)
* Feature: New libraries for [[MQTT/en | MQTT (IoT)]] and [[SomeIP/en | Some/IP (Automotive)]] (licensed addons)
* Feature: [[Settings_DebuggerSettings/en#Freeze_Values_are_Immutable | Immutable FreezeValues]]
* Feature: New [[Plot/Graph Action Blocks | '''Plot/Graph action blocks''']]
* Feature: New [[R Action Blocks | '''R action blocks''']]
* Feature: New [[ElementaryBlock_Element/en#Python_Script_Blocks|Python Action Blocks]], [[ElementaryBlock_Element/en#Ruby_Script_Blocks|Ruby Action Blocks]], Perl Action Blocks, [[ElementaryBlock_Element/en#Node.js-Script_Blocks|Node Action Blocks]], Go Action Blocks and TCL Action Blocks
* Feature / UI enhancement: screenshot dialog includes an "Attach" button.
* Feature / UI enhancement: embedded XML inspector in the attachment editor
* Feature / UI enhancement: "Generate" submenu to generate XPath accessors in the attachment editor, when showing XML.
* Feature: New library (StatisticDistributionsLibrary.ets) to generate random numbers with various distributions for statistic/monte carlo/simulations
* Feature: New library (Plot_Graph.ets) to demonstrate the new Plot/Graph actions
* Feature: New [[DiagramElements-Probe | probe types ]] to record values without checks (especially useful for plot/graph generation)
* Feature: timestamps can now have sub-millisecond resolution
* Feature: [[Selenium_WebDriver_Plugin|Selenium WebDriver Plugin]]
* Feature Qt enhancement: Inject support for 32/64bit applications including pre build clients
* Feature Qt enhancement: Add support for accessing complex properties like images, colors, ...
* Feature Qt enhancement: Menu item / Menu action support in GUI Browser
* Feature Qt enhancement: Extention of the qt block library
* Feature Qt enhancement: Replace QtScript with Qt JS api for Qt5 clients
* Feature Qt enhancement: Introduce a hook for customer client extension
* Feature Manual test plugin: New java based excel import
* Feature Manual Test plugin: Complete rework of the wizard
* Feature Manual test plugin: New manual test block library

* Performance: Speed improvement in testplan execution

* UI Enhancement: script actions are now initially created with a minimum set of special pins (actually: only the stdout pin is created initially). More pins can be added (and unused pins can be removed) in the schema editor via the "Special Pins" menu. We found that the vast majority of script steps only needed that single pin, and that diagrams look nicer without them (you can change this to the old behaviour via "''Settings''" - "''Look & Feel''" - "''Diagram Editor''" - "''Create all Special Pins Initially''").
* UI Enhancement: coloring by type is now on by default (if you don't like it, go to "''Settings''"-"''Look & Feel''"-"''Diagram Editor''"-"''Look-Elements''" and turn it off again)
* UI Enhancement: Limit the number of levels in follow activity
* UI Enhancement: ActivityTree shows activities with handled exceptions in orange (used to be red). Also, the handling activity shows where the handled exception was thrown. Finally, the automatic navigation to the first error (after a run) will skip over handled exceptions, to place you immediately to the activity which was responsible for the failure or error.
* UI Enhancement: goto "recently modified" and "recently executed" menus in the main-menu
* UI Enhancement: "''Select Step in Diagram''" menu-function in the activity log tree viewer
* UI Enhancement: "''Exchange Connections''" menu-function in the network editor
* UI Enhancement: "''Import Attachments''" tools menu-function (to import many files)
* UI Enhancement: more information and functions in the Diff-viewer; new menu item in the "''Extra''"-menu: "''Compare two Testsuite Files''"
* UI Enhancement: "''Add/Remove Tag''" menu functions (in tree) can also be applied recursively to children of the selected item
* UI Enhancement: if a step was selected when a new step is created (by the "''New Step''" function or by paste), the new step is automatically connected via trigger-out/trigger-in
* UI Enhancement: Connect multiple (same-named) pins
* UI Enhancement: fix (rewrite) JavaScript elementary code, when a pin is renamed
* UI Enhancement: rewrite script code when a pin is renamed
* STD-LIB: New action blocks: Stream[Set Binary Mode], Stream[Set Text Mode], Stream[Set Error-at-End Mode]
* STD-LIB: New action blocks to access and query [[DiagramElements-Probe | probes]] by ID (in Misc/Probes)
* STD-LIB: New logInconclusive and logError actions (similar to logFailure, these mark the test's outcome, but continue execution)
* STD-LIB: New actions to configure HTTPS for tls1.2 / tls1.1 (some sites no longer accept tls1.1)

== Release 2.11.1 (Fall 2017) ==
* Bugfix Release including all patches for Release 2.11
* Fix: Windows Automation - Stability
* Fix: Problems with OLE

== Release 2.11 (Spring 2017) ==
* Fix: JSON parameter save/reload fixed
* Fix: method name check in codeView was disabled
* Feature: "must be executed" attribute in action definition
* Feature: extensions to the expecco GUI automation framework
* Feature: new interfaces for automotive and mechanical engineering technoligies
* Feature: new host bound single user licensing scheme

* Packaging: new expecco product bundle: "expecco Testcenter" - test automation plus test and resource management in one package

== Release 2.10.1 (= 2.10 + Patches) ==
* Fix: keyboard focus for menu
* Backward Compatibility Fix: the fixes in the JavaScript "indexOf()"-functions (done in 2.8) lead to problems with a customer (which migrated from 2.7.5 to 2.10). For this, two flags have been added to the suite-attributes, which enforce the old behavior for individual and/or all imported libraries. This allows for old code (which expects the wrong 1-based indexOf return values) to coexist with new code (which expects the correct 0-based versions) within a single test suite.

* Feature: [[Settings UpdatesSettings/en|Patches can be loaded via HTTP]] (FTP was blocked in some customers' networks)
* Performance: Bulk data transfers to network drives under Windows.

== Release 2.10 (Fall 2016) ==
* Feature: Mobile Testing Plugin (renamed from "''Appium Plugin''") got more support functions to administer appium & adb connections
* Feature: new "Reimport Tool" for bulk reimport and library (dependency) checking
* Feature: DLL-mapping dialog in the settings. For a typical usage example, see [[AutoIt Library#Installation|Installation of AutoIt]]
* Feature: New blocks in the stdlib ("''Split by Size''" and "''Split by Element''"), to split collections (strings) into sized pieces or at a separator.
* Feature: New command line options to specify individual parameter values
* Feature: More formats supported for external parameter files (JSON)
* Feature: new [[Starting expecco via Command Line/en#Detailed_Option_Description|command line]] arguments: -E, -P:, --parameter:, --silent, --licenseServerHost, --licenseServerPort
* Feature: the new [[Java Interface Library v2|Java Bridge V2]]/DotNET Bridge V2 is now used by the default. The new bridge uses only a single port for communication (thus making firewall/router setup easier), supports casts, better controllable argument-type specification, is faster in its communication and supports asynchronous messages with lazy results. In case of backward compatibility problems, the old bridge is still available and can be used by changing the settings.
* Feature: custom print length of the pin and log values for the report
* Feature: [[CompoundBlock Editor-CompoundWorksheet Editor/en#Controlling_Logging_and_Tracing|"''Ignore All Skip in Trace''"]] settings to enforce a full trace (for debugging)

* Performance: (dramatic) speedup in some image handling functions.
* Performance: speedup (50%) in the XML reader.
* Performance: speedup initial startup by not loading unlicensed plugins

* UI enhancement: GUI Browser: double click on action/attribute item adds it to the list
* UI enhancement: GUI Browser: reconnect/fix autostart when deleting recorded steps
* UI enhancement: GUI Browser: better undo handling
* UI enhancement: GUI Browser: keep tree and selection on refresh (not all technologies)
* UI enhancement: better replace-step dialog in diagram editor (library filter added)
* UI enhancement: Line numbers in the attachment editor
* UI enhancement: Line numbers and trim-blank-lines option in multiline freeze value entry
* UI enhancement: color settings for red-green deficiency (in status color dialog)

* Change: SerialPort Plugin: the port parameter pins (baudrate, stop-bits, parity etc.) are now parameter pins. This will only affect you, if the open-serial-port block is triggered via one of those pins (which is very very unlikely)

* Fix: All leftover (unclosed) external connections (Sockets, Serial Lines, Bridges) are closed after a testrun, when in slave mode
* Fix: All leftover (unterminated) started appium servers are closed after a testrun, when in slave mode
* Fix: Multiline freeze value editor interpreted strings starting with digits as numeric value
* Fix: Multiline freeze value editor allows for empty lines at the end

== Release 2.9 (June/2016) ==
* Feature: Mobile Testing (aka "Appium")-Plugin: Add recorder
* Feature: Mobile Testing Plugin: Update capabilities
* Feature: Mobile Testing Plugin: Settings Dialog for setting up external auxiliary programs (adb, Appium Server, AVD Manager, SDK Manager)
* Feature: Mobile Testing Plugin: New menu for launching auxiliary programs (Appium Server, AVD Manager, SDK Manager)
* Feature: Mobile Testing Plugin: New buttons in Android Wizard to refresh the device list, launch AVD Manager, install APKs.
* Feature: Mobile Testing Plugin: Save and load connection settings in and from attachments in test suite.
* Feature: Mobile Testing Plugin: Allow editing and copying of connection settings.
* Feature: Mobile Testing Plugin: Allow adding arbitrary capabilities for forward compatibility.
* Feature: Mobile Testing Plugin Bundle: Update contents, in particular use Appium Server 1.4.16.
* Feature: Mobile Testing Plugin Bundle: Remove Android emulator from bundle as it is huge. If needed, download and install it separately.
* Feature: [[Java Interface Library v2|New Java Bridge (still experimental in 2.9)]]. The old Java Bridge is still available and enabled by default.

* UI enhancement: Mobile Testing Plugin: More verbose warning dialogs.
* UI enhancement: Mobile Testing Plugin: Remove obsolete "Emulator Settings" from connection dialog (using the wizard is superior now).
* UI enhancement: Mobile Testing Plugin: Make newCommandTimeout capability user visible
* UI enhancement: Mobile Testing Plugin: Remove unimportantView from default capabilities
* UI enhancement: Mobile Testing Plugin: Automatically select entry in Android Wizard if only one is available.
* UI enhancement: Mobile Testing Plugin: Highlight unknown capabilities to give a hint in case of bad spelling.
* UI enhancement: Mobile Testing Plugin: Add a search filter for packages in the Android Wizard.
* UI enhancement: General/Linux: Support for Anti-Aliased XFT-Fonts.

* STD-LIB: Image Save block supports writing of JPEG images.
* Mobile Testing Library: New blocks for multi-touch actions
* Mobile Testing Library: New block for reading capabilities from files
* Mobile Testing Library: New blocks for reading logs
* Mobile Testing Library: New block "Find Elements by XPath" for finding sets of elements
* Mobile Testing Library: New blocks for consecutive actions on single elements
* Mobile Testing Library: New block for taking screenshots
* Mobile Testing Library: New blocks for pressKeyCode API, make old blocks (sendKeyEvent API) obsolete

* Localization: Mobile Testing Plugin: German translation mostly complete.
* Documentation: Update and add more documentation to Appium library.

* Fix: Mobile Testing Plugin: Timeout in Android Wizard if adb does not return.
* Fix: Mobile Testing Plugin: Do not cut off multi-line status messages in Android Wizard.
* Fix: Mobile Testing Plugin: Fix error and bad behavior when cancelling file dialog in connection settings.
* Fix: Mobile Testing Plugin: Do not drop connection settings on connection error.
* Fix: Mobile Testing Plugin: Use Java path from Settings
* Fix: XML/XPath - accepts underscore ('_') and Unicode characters in element and attribute names.
* Fix: RemoteAccess Plugin - fix error waiting for prompt
* Fix: RemoteAccess Plugin - fix response in same line as command
* Fix: Java GUI Plugin - fix error in "Verify Path"

== Release 2.8 (Q4/2015) ==
'''Notice: You have to install a patch for expecco 2.7.5, if you want to load a Testsuite which was edited in expecco 2.8 and uses some of the new features! [[release2.8 incompatibilities|(More info)]]'''

* Feature: [[TableDrivenBlock Element|Table driven actions]]; these offer a simpler, table oriented interface
* Feature: Mobile Testing-Plugin (was "Appium"-Plugin) for Android and Apple iOS test automation for mobile devices
* Feature: Variable number of pins in groups ([[DiagramElements-Pin/en#Variable_Number_of_Pins|"Variable Pin Groups"]])
* Feature: First release of the [[User Defined Menu Items#Useful_Building_Blocks_for_Custom_Menu_Operations|Expecco Reflection Library]] (to automate expecco itself)
* Feature: Enum datatype: support for individual assigned enum values, described in the [[Datatype Editor/en#Enumeration_Types|Datatype Editor Documentation]] and the [[Datatype Element/en#Enumeration_Types|Datatype Element Documentation]] and also the [[Expecco API/en#Enum Type Functions|API Documentation]].
* Feature: [[Starting expecco via Command Line#Expecco_REST_Service_Interface|REST service]] for remote controlling expecco execution
* Feature: New [[ElementaryBlock Element/en#Ruby_Script_Blocks|Ruby actions]]
* Feature: Better execution directory settings for [[ElementaryBlock Element/en#Shell_Script_Blocks|Shell blocks]]
* Feature: New step attributes for more specific [[CompoundBlock Editor-CompoundWorksheet Editor/en#Step_Specific_Options_.28Context_Menu.29|"skip in log/trace"]] options (for looping actions)
* Feature: New user preference setting to ignore all [[CompoundBlock Editor-CompoundWorksheet Editor/en#Step_Specific_Options_.28Context_Menu.29|skip-in-log]] attributes (for debugging)
* Feature: "immediate fork new process" flag now also in block description or dynamically from elementary code
* Feature: Improved performer data type handling; virtual steps now only accept valid performers, and freeze value choices are filtered for valid performers.
* Feature: Option to start background action before or after pre-action
* Feature: New constraint datatype type (for better freeze value selection)
* Feature/Fix: compatibility of indexOf() / lastIndexOf() JavaScript functions (allow substring search)
* Feature: Data inspector for strings shows another (XML-DOM) tab if the string is an XML string. This tab shows the parsed XML DOM-tree.
* Feature: Attachments can now be declared as binary file attachment. These will not be interpreted; especially, no cr/lf translation and utf8 or similar character translation is performed. Binary attachments are required, e.g. to embed jar or other code files.

* UI enhancement: Multiline labels in steps (use "\" as line-separator)
* UI enhancement: Additional custom headline and custom text block in reports (can be filled in right before printing).
* UI enhancement: Can now also set breakpoints on steps and code lines of readonly actions (e.g. in an imported library)
* UI enhancement: Undo gives a warning when about to undo past the previous file-save state
* UI enhancement: Added a menu item in "Extras" - "Debugging" to stop [[User Defined Menu Items#Asynchronous_.28Background.29_Actions|background menu actions]]
* UI enhancement: Added more convenient pin-comment editing support to the schema editor
* UI enhancement: Text editor has a new "split" menu function in its tools-submenu
* UI enhancement: Better "New Step" and "Replace Step" dialogs in the diagram editor (showing preview, code and contents; also show attachments).
* UI enhancement: Better autoconnect and matching blocks search algorithm in the "Place and Select New Step" function (i.e. New Step function, when an output pin is selected)
* UI enhancement: New scale diagram function (scale and spread multiple steps)
* UI enhancement: Lint performs a number of checks on a block being edited and gives immediate warnings in the info line (same checks as in the tree's error- and special search tabs)
* UI enhancement: New lint-error check rules to detect consumed pin values in loops and multi-triggered chains.
* UI enhancement: Double click on a search item to navigate to it in the tree
* UI enhancement: Codeview and network view in the activitylog indicate that they are readonly.
* UI enhancement: Secondary navigation tree for drag&drop.
* UI enhancement: Warn if it is due time to check for updates.

* STD-LIB: Collection creator and multi-setter blocks with variable number of pins (alternating key-value pairs)
* STD-LIB: New DLL-Mapping block
* STD-LIB: New blocks "File [modification time]", "File [access time]" and "File [creation time]".
* STD-LIB: Additional blocks for event queue handling.
* STD-LIB: Additional blocks for static step-local storage.
* STD-LIB: Better versions for FAIL/WARN/INFO, LogFAIL, logWARNING and logINFO. New "Transcriber with Timestamp" action.
* STD-LIB: Fixed some collection-type issues (now pins are #-template-typed, instead of Collection), which required a downcast in many suites.
* STD-LIB: New blocks: "Trigger Periodically" and "Counter"
* STD-LIB: New blocks: "Enumtype symbol<->integer"

* Fix: Freeze value menu of unions of enums did not merge the individual enum values
* Fix: Freeze value menu of unions of constraint dataType-types
* Fix: The search breakpoints function (in the errors-tab of the treeview) now also finds statement breakpoints.
* Fix: Fixes and improvements in the SOAP, REST and WSDL frameworks
* Fix: Enum numeric value assignments were lost sometimes when saving/restoring
* Fix: Search for references of a variable did not find them in imported libraries
* Fix: Report of looped testplans (pre-action was reported multiple times)
* Fix: behavior of cancel pin (did neither drive triggerOut-pin, nor exception-pin)
* Fix: Fixes for crashes in follow mouse and backward (XPath) compatibility in WindowsAutomation Plugin
* Fix: The embedded type editor for defined classes lost its code window, when reopened on another class type.
* Fix: Proper class naming is now enforced in the type editor.

== Release 2.7.5 (2015-06-09) ==
'''New features''':
* The JavaFX plugin now supports keyboard input. Use the block "''Request Focus''" to focus an input field and the block "''Type Text''" to enter any text.

'''Bugfixes''':
* The JavaFX plugin now provides improved connection handling.

For expecco running under Linux you need glibc >= 2.14

Tested technology versions:
* Selenium
* The Java Bridge requires a JDK version 1.6 or higher
* JavaFX testing requires JavaFX 8
* Qt: Qt 2.6.3 (MinGW, vs2008), Qt 4.8.4 (MinGW, vs2008, vs2010, vs2013), Qt 5.4.2 (vs2010, vs2013)
* .NET
* MFC
* HTML 5
* DevExpress
* Android
* iOS
* Windows CE/Mobile Phone
* CANoe: 8.2 SP4
* WSDL-Import: it is required that you re-import your WSDL-Definitions in your Testsuites

==Release 2.7.1 ==
* Convenient menu functions to add the special [[Expecco API#Using a Particular JVM Connection / Executing Groovy on a Possibly Remote Machine|"java" and "groovy"]] input pins to a Groovy elementary block.
* Standard library: new blocks: "''Directory [ Contents as Filenames ]''", "''Directory [ Contents as Pathnames ]''", "''Directory [ Contents as Basenames ]''", "''File [ isReadable? ]''" and "''File [ isWritable? ]''"

==Release 2.7 ==
* Patches go into a release specific directory (e.g. patches-2.7.0.5)
* configurable external editor for attachments and csv data (e.g. excel or openoffice calculator)
* tree view: markers in search lists; add to/remove from remembered list menu items
* tree view: folders can have tags, too
* tree view: per-tag icons in tree
* [[Starting expecco via Command Line/en#Utility_Functions|"--diff" command line option]]
* [[Starting expecco via Command Line/en#Startup|"--settings" command line option]]
* Scatter/Gather composition of test plans from multiple suites [[Starting expecco via Command Line/en#Scatter Gather Test Suite Composition|via command line arguments]]
* library: background OS process and background block actions
* improved type checks and preference settings
* schema editor: cursor up/down keys in pin name fields
* schema and diagram editor: additional menu functions in multiple-pin selection menu
* new blocks in the StandardLibrary: ExceptionClassifier, WriteCSV, Load/Save Environment from/to CSV
* [[SAP Testing|SAP plugin and VBScript action blocks]]
* change in the handling of Groovy callbacks. Please read [[Expecco API/en#Attention_.2F_Warning|"Attention / Warning"]] and [[Expecco API/en#Special_Functions|"Special Functions"]] in the Groovy API documentation.
* improved Groovy debugging support
* new common Android and iPhone/iPad testing framework
* option to save a per-run report, when a suite is executed in a loop (especially useful, when running until fail or until success)
* block assertions: assert-executed / assert-all outputs written / assert any output written
* License server support

==Release 2.6.2 bugfix release - April 2014 ==
Thus is a stable release consisting of the 2.6.1 base version INCLUDING all 2.6.1 patches (up to April).

==Release 2.6.1 update - January 2014 ==
* [[Expecco API#Groovy_Elementary_Blocks|groovy action]]: the java-bridge can be passed in via pin named "java" or environment var named "JAVA". GroovyShell can be passed in via pin named "groovy" or variable named "GROOVY". Pins are optional for backward compatibility.

==Release 2.6 - November 2013 ==
* New testplan execution loop mode: "loop until required test fails"
* More options for automatic check for and installation of updates & patches
* Better default directories in file open/save/import dialogs.
* Tuned automatic reimport when multiple libraries are imported.
* Improved Java object inspector
* New attachment contents representation modes.
* Step tooltips include the underlying block's tree location.
* Shift click on connection selects all underlying connections.
* Give an indication (colorize menubar) if running with root/Admin rights.
* Option to put the custom operations menu into the top menu
* Additional tab in tree view to search by item-type
* Additional search options for interfaces and concrete actions
* Various bug fixes & enhancements:
** handle duplicate attachment filenames,
** fixed some type conversions,
** fixed clipboard handling under XWindow/Qt desktop,
** fixed non-changing testplan/testitem spec page.
** added string search in resources, skills and inventories
** no longer close expanded tree items when reimporting
** fixed making an imported library writable, which is imported by another sub-import
** fixed freeze of template pin to boolean/enum
** fixed enum values which start with a digit (aka '001 aaa')
** remove freeze value connection via menu

==Release 2.5 ==
* Can refer to [[Environment Editor#Initialization Types|shell environment variables]] in an environment variable's initializer.
* New elementary block type: Groovy Code. Installs script code to be executed in a Java target or a local JVM.
* New keyword driven actions
* Additional checks in save dialogs to prevent overwriting another testsuite/library
* Optional automatic reimport or check for reimportable imports (configure via settings dialog)
* Additional freeze value validation when types are edited
* New plugin: Jar Import
* New and much improved manual test import plugin
* Speedup, improvements and fixes in the JavaBridge plugin
* Menu actions can [[Misc Editor#Background_Actions|execute in the background]] (name as "...&")
* Background actions in testplan and testcase
* Much faster: startup, plugin loading and bridge communication
* Multiple freeze value menu organizations for enum types (hierarchical selection)

===Release 2.5.1 - July 2013 ===

* Automatic & semiautomatic update from server

==Release 2.4 - February 2013 ==
This is a bugfix release, in which various patches and small enhancements from the past few months have been integrated.

==Release 2.3 - December 2012 ==
* New integrated GUI Browser
* New menu functions: "minimize/restore all Windows"
* Polarion compatible report
* Improved Project-Diff-Browser

==Release 2.2==
* New SchemaEditor menu functions: copy/paste pin interface
* New plugin: [[GembirdPowerControlPlugin Reference#|Gembird Power Control Plugin]]
* New debug-menu function: "close all temporary windows"
* [[Probe|Probes]]; easy recording and check of pinValues
* JUnit compatible report
* HTTP and SOAP transmission log (optional on Transcript)
* Fixed WSDL/SOAP for document-style operations
* Better inspector (hex dump tab, hex representation of floats)

==Release 2.1 - November 2011==
* Condition variables for simple (and easy to use) control of testcase execution
* [[Webservices#REST_Baustein|REST-Call]] blocks
* Option to disable logging of activityNotifications (from the underlying language framework)
* URL-override for SOAP service call blocks via the SOAP_URL environment variable.
* Access to the certificate store (for SSL/HTTPS), allows adding and removing individual certificates
* Elementary steps can have a variable number of output-pins (for multiplexer, dispatcher, round-robin generators etc.)
* New menu function: "Generate Value Extractor" for Dictionary-typed pin values. (in the activityLog, output pin-data menu)
* New tree-menu function: "Refactor"->"Change Variable Access", to search for and replace environment variable references.
* New datatype [[Datatype Element#Special_Types|"struct"]], to represent arbitrary compound (struct) values.
* GUI improvements: better annotation-text editors; line numbers, tags in file viewer
* Allow for multi pin-value parametrization in testplan (block with multiple inputs in a testplan item)
* Proxy support for HTTP-fetch blocks
* Recording feature for Java Swing GUIs
* Enhanced Java Swing Function Block Library
* GUI Browser improvements: tree view with widget specific icons, record tree actions

==Release 2.0==
* Elementary steps can have a variable number of input-pins (improves the format, plus, string-concat and many other blocks)
* Statistic page added to the project editor
* Improved manual test import plugin; nicer Manualtest runner GUI; user definable manual test GUI
* Allow for pin-value parametrization in testplan (block with a single input parameter in a testplan item)
* Configurable max. cleanup time after terminating a run; Confirmation Dialog when longer.
* ActivityLog: added "Select in Tree" from log-entry
* HTTPS / SSL Support for HTTP blocks

Hauptseite

2018-01-07T13:54:07Z

Ab:

<table border=0 cellspacing=8 width="100%">
<h1>expecco</h1>
<tr>
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage.png|30px]]   Für Einsteiger<hr/>
:* [[Was ist expecco ? | Was ist expecco?]]
:* [[Glossary | Begriffserklärung]]
:* [[Einsteiger Tutorials | Einsteiger Tutorials]]
:* [[expecco UI | expecco UI]]
:* [[FAQ | FAQ]]

 

<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage5.png|30px]]   Installation<hr/>
:* [[Installation | Installation]]
:* [[Personal Settings | Persönliche Einstellungen]]
:* [[Configuration & Setup | Konfiguration]]
:* [[Anbindung expecco ALM | Anbindung expecco ALM]]
:* [[Spezifische Anpassung | Spezifische Anpassung]]

 

<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage4.png|30px]]   Werkzeuge<hr/>
:* [[Debugger | Debugger]]
:* [[Editoren | Editoren]]
:* [[API von Elementaraktionen | API von Elementaraktionen]]
:* [[Standard Libraries/Bibliotheken | Standard Libraries/Bibliotheken]]
:* [[Weitere Werkzeuge | Weitere Werkzeuge]]
:* [[Weitere Funktionen | Weitere Funktionen]]
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage6.png|30px]]   Reportgenerierung<hr/>
:* [[Report Generation | Reportgenerierung]]

 
 
 

</tr>
</table>

<table border=0 cellspacing=8 width="100%">
<tr>
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Erweiterung_plugin.png|30px]]  Erweiterungen (Plugins)<hr/>
:* [[Schnittstellen zum SUT | Schnittstellen zum SUT]]
:* [[GUI Testing | GUI Testing]]
:* [[Code Ausführung | Code Ausführung]]
:* [[Daten/Nachrichten/Dokument Formate | Daten/Nachrichten/Dokument Formate]]
:* [[Unterstützung der Tests | Unterstützung der Tests]]
:* [[QM Schnittstellen| QM Schnittstellen]]
:* [[Import/Export von Spezifikationen | Import/Export von Spezifikationen]]
:* [[Kommunikation/Protokolle | Kommunikation/Protokolle]]
:* [[Databases | Databases]]
:* [[API | API]]
:* [[NoSQL | NoSQL]]
:* [[Sonstige Plugins | Sonstige Plugins]]
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage3.png|30px]]  Elemente der Testsuite<hr/>
:* [[Tree Elements/en | Tree Elemente]]
:* [[Folder Element/en | Ordner]]
:* [[Testplan Element | Testplan Element]]
:* [[Aktionen/Aktionsblöcke | Aktionen/Aktionsblöcke]]
:* [[Datatype Element| Datentyp Element]]
:* [[Inventory Element| Inventory Element]]
:* [[Skill Element | Skill Element]]
:* [[Resource Element | Ressouurce Element]]
:* [[Attachment Element/en | Anhänge]]
:* [[ReportTemplate Element | Report Templates]]

 

<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Diagramm.png|30px]]  Diagramm - Elemente<hr/>
:* [[DiagramElements-Step/en| Schritt]]
:* [[Pins (Ein - Ausgänge) | Pins (Ein - Ausgänge)]]
:* [[Code Ausführung | Code Ausführung]]
:* [[DiagramElements-Connection | Verbindung]]
:* [[DiagramElements-Pin/en | Pin Beschreibung]]
:* [[DiagramElements-Annotation| Notiz]]
:* [[DiagramElements-Probe/en | Messfühler]]

 
 
 

<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Refresh.png|30px]]  Sonstiges<hr/>
:* [[expecco Mobile Remote App | expecco Mobile Remote App]]
:* [[Release Notes 2.x | Release Notes 2.x]]
:* [[Release Notes 1.x | Release Notes 1.x]]
:* [[Future releases expecco | Zukünftige Releases]]
:* [[Smalltalk | Smalltalk]]

 
 
 
 
 
 
 

</tr>
</table>

<table border=0 cellspacing=8 width="100%">
<h1>expecco ALM</h1>
<tr>
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Sonstiges-Info.png|30px]]  Allgemein<hr/>
:* [[Was ist expecco ALM ? | Was ist expecco ALM?]]
:* [[Anbindung expecco ALM | Anbindung expecco ALM]]

 
 
 
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage5.png|30px]]  Installation/Einrichten<hr/>
:* [[expecco ALM Installation | Installation]]
:* [[expecco ALM Einrichten Vorgehensweise | expecco ALM Einrichten]]
:* [[... | Benutzer Einrichten (*empty)]]
:* [[... | Projekt Einrichten (*empty)]]
:* [[... | Workflow Einrichten (*empty)]]
:* [[Einstellungen | Einstellungen (*empty)]]
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Refresh.png|30px]]  Sonstiges<hr/>
:* [[expecco ALM App | expecco ALM App]]
:* [[Lizenzserver expecco ALM | Lizenzserver expecco ALM]]
:* [[Tutorials expecco ALM | Tutorials (*empty)]]
:* [[expecco ALM Release Notes | Release Notes]]
:* [[FAQ | FAQ]]

Hauptseite

2018-01-07T13:53:44Z

Ab:

<table border=0 cellspacing=8 width="100%">
<h1>expecco huhu</h1>
<tr>
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage.png|30px]]   Für Einsteiger<hr/>
:* [[Was ist expecco ? | Was ist expecco?]]
:* [[Glossary | Begriffserklärung]]
:* [[Einsteiger Tutorials | Einsteiger Tutorials]]
:* [[expecco UI | expecco UI]]
:* [[FAQ | FAQ]]

 

<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage5.png|30px]]   Installation<hr/>
:* [[Installation | Installation]]
:* [[Personal Settings | Persönliche Einstellungen]]
:* [[Configuration & Setup | Konfiguration]]
:* [[Anbindung expecco ALM | Anbindung expecco ALM]]
:* [[Spezifische Anpassung | Spezifische Anpassung]]

 

<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage4.png|30px]]   Werkzeuge<hr/>
:* [[Debugger | Debugger]]
:* [[Editoren | Editoren]]
:* [[API von Elementaraktionen | API von Elementaraktionen]]
:* [[Standard Libraries/Bibliotheken | Standard Libraries/Bibliotheken]]
:* [[Weitere Werkzeuge | Weitere Werkzeuge]]
:* [[Weitere Funktionen | Weitere Funktionen]]
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage6.png|30px]]   Reportgenerierung<hr/>
:* [[Report Generation | Reportgenerierung]]

 
 
 

</tr>
</table>

<table border=0 cellspacing=8 width="100%">
<tr>
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Erweiterung_plugin.png|30px]]  Erweiterungen (Plugins)<hr/>
:* [[Schnittstellen zum SUT | Schnittstellen zum SUT]]
:* [[GUI Testing | GUI Testing]]
:* [[Code Ausführung | Code Ausführung]]
:* [[Daten/Nachrichten/Dokument Formate | Daten/Nachrichten/Dokument Formate]]
:* [[Unterstützung der Tests | Unterstützung der Tests]]
:* [[QM Schnittstellen| QM Schnittstellen]]
:* [[Import/Export von Spezifikationen | Import/Export von Spezifikationen]]
:* [[Kommunikation/Protokolle | Kommunikation/Protokolle]]
:* [[Databases | Databases]]
:* [[API | API]]
:* [[NoSQL | NoSQL]]
:* [[Sonstige Plugins | Sonstige Plugins]]
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage3.png|30px]]  Elemente der Testsuite<hr/>
:* [[Tree Elements/en | Tree Elemente]]
:* [[Folder Element/en | Ordner]]
:* [[Testplan Element | Testplan Element]]
:* [[Aktionen/Aktionsblöcke | Aktionen/Aktionsblöcke]]
:* [[Datatype Element| Datentyp Element]]
:* [[Inventory Element| Inventory Element]]
:* [[Skill Element | Skill Element]]
:* [[Resource Element | Ressouurce Element]]
:* [[Attachment Element/en | Anhänge]]
:* [[ReportTemplate Element | Report Templates]]

 

<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Diagramm.png|30px]]  Diagramm - Elemente<hr/>
:* [[DiagramElements-Step/en| Schritt]]
:* [[Pins (Ein - Ausgänge) | Pins (Ein - Ausgänge)]]
:* [[Code Ausführung | Code Ausführung]]
:* [[DiagramElements-Connection | Verbindung]]
:* [[DiagramElements-Pin/en | Pin Beschreibung]]
:* [[DiagramElements-Annotation| Notiz]]
:* [[DiagramElements-Probe/en | Messfühler]]

 
 
 

<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Refresh.png|30px]]  Sonstiges<hr/>
:* [[expecco Mobile Remote App | expecco Mobile Remote App]]
:* [[Release Notes 2.x | Release Notes 2.x]]
:* [[Release Notes 1.x | Release Notes 1.x]]
:* [[Future releases expecco | Zukünftige Releases]]
:* [[Smalltalk | Smalltalk]]

 
 
 
 
 
 
 

</tr>
</table>

<table border=0 cellspacing=8 width="100%">
<h1>expecco ALM</h1>
<tr>
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Sonstiges-Info.png|30px]]  Allgemein<hr/>
:* [[Was ist expecco ALM ? | Was ist expecco ALM?]]
:* [[Anbindung expecco ALM | Anbindung expecco ALM]]

 
 
 
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Icon_Landingpage5.png|30px]]  Installation/Einrichten<hr/>
:* [[expecco ALM Installation | Installation]]
:* [[expecco ALM Einrichten Vorgehensweise | expecco ALM Einrichten]]
:* [[... | Benutzer Einrichten (*empty)]]
:* [[... | Projekt Einrichten (*empty)]]
:* [[... | Workflow Einrichten (*empty)]]
:* [[Einstellungen | Einstellungen (*empty)]]
<td font size="5" bgcolor=#ECF0F3 width="20%" height="100" align="left" valign="top>
  [[Datei:Refresh.png|30px]]  Sonstiges<hr/>
:* [[expecco ALM App | expecco ALM App]]
:* [[Lizenzserver expecco ALM | Lizenzserver expecco ALM]]
:* [[Tutorials expecco ALM | Tutorials (*empty)]]
:* [[expecco ALM Release Notes | Release Notes]]
:* [[FAQ | FAQ]]

Settings HotKeySettings/en

2017-10-30T13:38:33Z

Ab: /* Hotkey Setup */

== Hotkey Settings ==

The purpose of hotkeys is to allow some control over expecco,
while recording a GUI interaction, without having to move the mouse or click on something
(i.e. to avoid both interacting with the application and recording that interaction).
Hotkeys are caught by expecco before they are sent to any application.
Thus, any key which is defined as hotkey can NOT be sent to ANY window.

The Hotkey service is currently available only for Windows operating systems. The support for other operating systems is part of the roadmap and will be integrated in a future expecco release.

=== Available Hotkey Functions ===

In this version expecco suport the following hot key functions:
 
<UL>
<LI>Start a testrun in expecco (the hot key will be delegated to the last active browser window)
<LI>Stop a running test execution
<LI>Toggle (start/stop) the recording mode in expecco GUIBrowser
<LI>Toggle (start/stop) the follow mouse mode in expecco GUIBrowser
</UL>
 
The state of the hotkey service (running/stopped) is shown in the setting dialog.

=== Hotkey Setup ===

In the hotkey setup dialog you can specify the hotkeys you want to use within expecco. The default setting for the hotkeys is disabled.
In the table (see image below) you can enable/disable each hotkey specification row by a check toggle. If disabled (check toggle is off),
the hotkey will not be activated if the service is started. In the Hotkey and Modifier columns you can defined the keys you want to assign
to the hotkey function.
 
 
The hotkey settings can not be changed during the service is running.
 
 

[[Datei:HotkeySetupDialog.png]]

 
 
If you want to start the hotkey service directly after the expecco startup, please enable the check box "Auto start hot key event listener". If you want to start the hotkey service manually press the "Start" button. If the "Start" button is disabled you may have unapplied changes in the settings. Please apply them first. After that the "Start" button should be enabled and ready for starting the service.

[[Category:Settings]]

Settings HotKeySettings/en

2017-10-30T13:28:21Z

Ab: /* Hotkey Setup */

== Hotkey Settings ==

The purpose of hotkeys is to allow some control over expecco,
while recording a GUI interaction, without having to move the mouse or click on something
(i.e. to avoid both interacting with the application and recording that interaction).
Hotkeys are caught by expecco before they are sent to any application.
Thus, any key which is defined as hotkey can NOT be sent to ANY window.

The Hotkey service is currently available only for Windows operating systems. The support for other operating systems is part of the roadmap and will be integrated in a future expecco release.

=== Available Hotkey Functions ===

In this version expecco suport the following hot key functions:
 
<UL>
<LI>Start a testrun in expecco (the hot key will be delegated to the last active browser window)
<LI>Stop a running test execution
<LI>Toggle (start/stop) the recording mode in expecco GUIBrowser
<LI>Toggle (start/stop) the follow mouse mode in expecco GUIBrowser
</UL>
 
The state of the hotkey service (running/stopped) is shown in the setting dialog.

=== Hotkey Setup ===

In the hotkey setup dialog you can specify the hotkeys you want to use within expecco. The default setting for the hotkeys is disabled.
In the table (see image below) you can enable/disable each hotkey specification row by a check toggle. If disabled (check toggle is off),
the hotkey will not be activated if the service is started. In the Hotkey and Modifier columns you can defined the keys you want to assign
to the hotkey function.
 
 
The hotkey settings can not be changed during the service is running.
 
 

[[Datei:HotkeySetupDialog.png]]

 
 
If you want to start the hotkey service directly after the expecco startup, please enable the check box "Auto start hot key event listener". If you have changed the settings, please apply them first. After that the hotkey service is ready for starting.

[[Category:Settings]]

Settings HotKeySettings/en

2017-10-30T13:21:27Z

Ab: /* Hotkey Setup */

== Hotkey Settings ==

The purpose of hotkeys is to allow some control over expecco,
while recording a GUI interaction, without having to move the mouse or click on something
(i.e. to avoid both interacting with the application and recording that interaction).
Hotkeys are caught by expecco before they are sent to any application.
Thus, any key which is defined as hotkey can NOT be sent to ANY window.

The Hotkey service is currently available only for Windows operating systems. The support for other operating systems is part of the roadmap and will be integrated in a future expecco release.

=== Available Hotkey Functions ===

In this version expecco suport the following hot key functions:
 
<UL>
<LI>Start a testrun in expecco (the hot key will be delegated to the last active browser window)
<LI>Stop a running test execution
<LI>Toggle (start/stop) the recording mode in expecco GUIBrowser
<LI>Toggle (start/stop) the follow mouse mode in expecco GUIBrowser
</UL>
 
The state of the hotkey service (running/stopped) is shown in the setting dialog.

=== Hotkey Setup ===

In the hotkey setup dialog you can specify the hotkeys you want to use within expecco. The default setting for the hotkeys is disabled.
In the table (see image below) you can enable/disable each hotkey specification row by a check toggle. If disabled (check toggle is off),
the hotkey will not be activated if the service is started. In the Hotkey and Modifier columns you can defined the keys you want to assign
to the hotkey function.
 
 
The hotkey settings can not be changed during the service is running.
 
 

[[Datei:HotkeySetupDialog.png]]

 
 
If you want to start the hotkey service directly after the expecco startup, please enable the check box "Auto start hot key event listener". The hotkey service can only be started if the changes within the settings dialog are accepted.

[[Category:Settings]]

Starting expecco via Command Line/en

2017-04-02T12:53:50Z

Ab:

== Introduction ==

expecco can be started manually via the command line, by batch or shell scripts or automatically via the crontab (Unix) or scheduled tasks / services (Windows) mechanism of the operating system. Thus, you can have tests to execute unattended and without GUI "overnight". This is also the method to integrate expecco with other quality tools, such as Jenkins, HP-Quality Center, Polarion, expeccoALM etc.

Command line options allow for test suites to be loaded, executed and result files being generated without requiring user interaction.

In addition to the above, expecco can also be started in a slave mode as a service, to wait for incoming test-run request from a QM system, such as expeccoALM or Polarion. Expecco can respond to request via SOAP or REST calls to load, execute and report test suites. The expeccoNET automation environment assumes that expecco is already running on each slave host, and each has been started with a "--server" command line argument. It uses HTTP+SOAP/REST to communicate with those expecco slaves by default.

In this later "slave mode", expecco is installed to run as a daemon process (under Unix) or as a service (under Windows), and will be automatically started by the operating system, when it boots. The details of how it is installed vary between operating systems: under Unix, it needs to be registered in the init-tab-folder, under Windows it needs to be installed as a Windows service.

== Command Line ==

If expecco is started without command line arguments, it will open up showing the initial welcome screen. The same behavior as if started via the desktop.

With a single file argument, expecco will read a test suite from the given file and open an editor window on it (but will not execute it).

'''expecco <testsuite filename>'''

This is the same behavior as if a test suite file (.ets) is dropped onto the expecco icon via the desktop.

The simplest command line to execute a test suite is:

'''expecco --execute <testsuite filename> ...'''

:<testsuite filename> is the test suite's filename, as saved from within the expecco GUI application. This should be a saved ".ets" testSuite file. If more than one test suite filename is given, each is processed in sequence. All top-level test plans as found in the test suite(s) are executed (see below for more options).

:By default, the overall execution outcome is returned by the command's return value (exit code), which is
::0 - all PASSED
::non-zero - any ERROR, FAILURES or INCONCLUSIVE items.

The return value is useful if expecco is started via a makefile, or from jenkins for example. If the caller needs a different exit code, use one of the exitCodeOnXXX options as described below. This is useful to avoid a ''make'' or ''jenkins'' process from stopping.

To get a list of available options, type:
'''expecco --help'''

=== Command Line Options ===
Command line options are handled at two places: the runtime system (Smalltalk/X VM) and the expecco application itself.
When expecco is started, the VM is first to look for command line arguments and processes any of the VM options, until
a non-VM option is encountered. It passes the remaining options to expecco's main entry.
Thus, any option which is given after the first non-VM option will not be handled by the VM, but by expecco. Therefore, no VM options should be placed after the first non-VM option. VM options are marked as "''VM option''" in the list below.

Also, some options are specific to the operating system, on which expecco is executed. These are marked as "''Windows''", "''Linux''" etc.

=== Recommended Command Line Options ===

To start expecco on an existing test suite, use:

'''expecco <testsuite filename>'''

this is also the way expecco is started, when a test suite file is double-clicked on the Linux or Windows desktop, or when a test-suite document is dropped onto the expecco icon.
The above opens the expecco GUI and loads the given test suite initially. However, it does not automatically execute any test.

To execute a suite, add a "'''--execute'''" argument (or in expecco 2.10, "-E"), as in:

'''expecco --execute <testsuite filename>'''

You will notice, that expecco shows a banner intitially; this can be disabled with a '''--noBanner''' option. Also, under windows, a small tray icon is shown in the lower right, which provides a controlling UI. This is disabled with '''--noTray'''.

Finally, as mentioned before, the test's outcome is reported via the exit code. If you want a little more information on the status of individiual test cases, use a '''--verdicts''' option.

This makes the following a good start for your command line:

'''expecco --noBanner --noTray --verdicts --execute <testsuite filename>'''

or, if you want to use a special parameter-file, to provide values for (some of) the project-variables:

'''expecco --noBanner --noTray --verdicts --parameter <param-file> --execute <filename>'''

Parameter files are XML, CSV or JSON-files containing key-value pairs. They are usually created by saving an environment from within the expecco GUI (see [[Environment Editor]]).

All of the above command lines opened an expecco UI window.
To execute a suite without GUI, add a "'''--noWindow'''" argument.

To compose "scatter-gather" test cases from possibly multiple suites, found in a directory use:

'''expecco --suiteDirectory <dirName> --testCaseNames "T01,T02,T05" --execute'''

or, to explicitly specify the suite-files where test cases are taken from, use:

'''expecco --testCaseNames "T01,T02,T05" --execute <suiteFile1>.ets <suiteFile2>.ets ...'''

Finally, to get a report, add a "'''--xxxReportFile <fileName>'''" argument, as in:

'''expecco --noBanner --noWindow --noTray --verdicts --parameter <param-file>''' \
''' --pdfReportFile result.pdf --execute <filename>'''

All options are described in more detail below.

=== Executing Multiple Test Suites in Sequence ===

It is possible to run multiple (possibly different) test suites with one command line to reduce startup and project loading times.
For this, provide multiple "--execute <filename>" arguments to the command line, as in:

'''expecco --execute <suiteFile1>.ets --execute <suiteFile2>.ets ...'''

with this command line, expecco first executes the toplevel testplan(s) from "suiteFile1.ets", then those from "suiteFile2.ets". All parameters (i.e. top-level variable values) will be taken from within the corresponing suite file.

To change individual parameters, use "--parameter:key=value" arguments before the corresponing --execute argument. For example, to execute the same suite with different parameters, use a command line like:

'''expecco --parameter:device=samsung --execute mobileTest.ets''' \
''' --parameter:device=nexus --execute mobileTest.ets'''

=== Opening a Previous Result File ===

As described below, expecco can generate result files in various formats and different detail. The pdf, html and junit outputs will contain summary information to be read by humans, archived or to be passed to other programs (eg. to jenkins for statistics).

The native result file (.elf) contains all trace and logging information including the original test suite.

As such, it can be archived to ensure that the test result can always be associated to the exact suite being executed, even if the suite file is lost or has been modified in the meanwhile.

These .elf result files are generated either via corresponding command line options or manually via the "''Test Results''"-"''Save Result As...''" menu item.
Like regular suite files, they can be opened via the command line or via the "''File''"-"''Open...''" menu item.

When opened, the original suite (at the time of execution), the trace- and log data and the execution times will be presented. It is even possible to re-execute individual blocks, test plans or the whole suite.

This feature is very powerful, in that it allows for the result file to be given to a developer and will help to analyse the data values, control flows and even to rerun tests and reproduce errors/failures.

=== Detailed Option Description ===

==== Information/Debugging/Logging ====

*'''<code>--help</code>''' Prints an up-to-date list of possible options and command line arguments.

*'''<code>--version</code>''' Prints the expecco release identification and exits.

*'''<code>--noBanner</code>''' (''VM option'') Suppress the splash startup banner.

*'''<code>--console</code>''' (''VM option'', ''Windows only'') Open a debug console window for Stdout and Stderr.

*'''<code>--verbose</code>''' (''VM option'') Additional startup, execution and result info is sent in human readable format to the stderr output. This is mainly meant to analyze startup problems and is actually more useful for expecco developers. It may be too much of printout, so try "''--verdicts''" instead.

*'''<code>--debug</code>''' Turns on startup debugging. By default, if an error occurs during startup, expecco terminates itself. With this option enabled, a command line debugger is opened instead. This is probably only useful for plugin developers.

*'''<code>--silent</code>''' Suppresses most info, warning and error messages which are sent to stderr/stdout. This is mainly meant to remove unwanted informational messages (for example, when plugins cannot be loaded during startup, etc.). (this option is available with expecco vsn >= 2.10)

==== Startup ====

*'''<code>--settings <fileName></code>''' Force using <fileName> instead of the default "<code>~/.expecco/.expeccoPreferences</code>" to be used for the settings file name. Useful if you want different setups to be linked to different desktop icons, or to start expecco with particular settings from a batch or shell script. To generate a preferences file, open the "''Extras''" - ''Settings''" dialog, change the settings as required, and select the "''File''"-"''Save As...''" menu item.

*'''<code>--licenseFile <fileName></code>''' Use this license, instead of the default "<code>~/.expecco/.expeccoLicense</code>". If a license server (floating licenses) is used, the license server's hostname and port information is read from the settings file.

*'''<code>--licenseServerHost <hostName></code>''' Use this host as license server, instead of the one specified in the settings file (or if no settings file was ever specified). This may be needed when running expecco as a test slave (daemon or service). (this option is available with expecco vsn >= 2.10)

*'''<code>--licenseServerPort <portNr></code>''' Use this port-nr when contacting the license server, instead of the one specified in the settings file (or if no settings file was ever specified). This may be needed when running expecco as a test slave (daemon or service). (this option is available with expecco vsn >= 2.10)

*'''<code>--noTray</code>''' (''Windows only'') Disable the tray control icon (server and execute modes only).

*'''<code>--tray</code>''' Force a tray window to be shown, even if running in non-server (slave) mode. The tray window displays the current execution status, memory situation, thread status and other internal information, which is probably only useful for developers. (this option is available with expecco vsn >= 2.10)

*'''<code>--noWindow</code>''' Do not open the main window (useful when scripting or executing only).

*'''<code>--noDisplay</code>''' Do not open any window (useful when scripting or executing only).

*'''<code>--noPlugins</code>''' Disable plugin loading. This makes startup somewhat faster, depending on the number of plugins found in your installation directory. You can still force individual plugins to be loaded using the "'''--loadPlugin'''" option. Use "''--noPlugins''" followed by a list of individual "''--loadPlugin''" options, to tune startup time with a minimum set of required plugins being loaded.

*'''<code>--loadPlugin <pluginName></code>''' Force loading a specific plugin. This is only useful if a "'''--noPlugins'''" option was given before. ''pluginName'' is the name of the folder in the "plugin" folder (under the expecco installation folder). Use "''--noPlugins''" followed by a list of individual "loadPlugin" options, to tune startup time with a minimum set of required plugins being loaded.

*'''<code>--noUpdateCheck</code>''' If configured by the user's settings, expecco automatically checks for updates and patches when started (by checking the exept web-server for the presence of new patch files). This option disables that check, even if configured in the settings. Notice, that this is usually controlled by the user settings; however, in situations where settings are shared among multiple machines (network drive) and a test host has no (or should not have) internet access, it may be useful to disable this from the command line. It is especially useful, if you are disconnected from the Internet (isolated test-lab), to avoid time delays resulting from connection failures.

*'''<code>--requireLogin</code>''' Opens expecco in a (lightweight) multi-user mode, in which a username must be entered before the actual interaction with expecco begins. This user name will be used to load custom per-user settings (named "<code>.expeccoSettings_<name></code>") and will also be used in the generated reports. Also, the "''File''" menu will contain an additional "''Logout''" menu item, which brings back the initial login dialog. This mode is useful, if expecco is used on a machine by multiple users, and expecco should remain opened (i.e. as a test stand). For example in a production floor, where tests are executed in multiple shifts by multiple operators.

*'''<code>--load <fileName or packageName></code>''' Loads a class file, extension or user plugin. The argument must be either the name of a Smalltalk source or binary file, or the name of a package (which must be found in the "<code>packages</code>" subfolder under the expecco installation folder). For details on how to generate such packages, read [[Creating_new_Class_Library_Packages/en | "Creating new Class Library Packages"]].

==== Test Execution ====
*'''<code>--execute <fileName></code>''' read and execute a suite. Starting with expecco 2.10, you can also use "-E <fileName>", which makes the command line a bit shorter.

*'''<code>--execute</code>''' without a filename, this should be the last argument of a scatter-gather dynamically generated suite command (see below: scatter-gather tests)

==== Test Selection ====

the following options allow for individual test plans to be selected for execution from a suite which contains multiple test plans. Without any such option, ''--execute'' will run all top-level testplans found in the suite in sequence.

*'''<code>--testPlanName <namePattern></code>''' Only execute test plans with a matching name. For backward compatibility, "'''<code>--testSuiteName <namePattern></code>'''" is still supported and has the same effect.

*'''<code>--testPlanTag <tagPattern></code>''' Only execute test plans with a matching tag. For backward compatibility, "'''<code>--testSuiteTag <tagPattern></code>'''" is still supported and has the same effect.

*'''<code>--testPlanID <uuid></code>''' Only execute that particular test plan (repeat to execute multiple test plans). Starting with release 2.7, the following shortcut can also be used: '''<code>--testSuiteID "<uuid1>,<uuid2>,...,<uuidN>"</code>'''. For backward compatibility, "'''<code>--testSuiteID <uuid></code>'''" is still supported and has the same effect.

==== Scatter Gather Test Suite Composition ====

these options allow for a test plan to be composed out of a single or multiple of individual suite files. When composing, a new test plan is temporarily created, which contains the specified test cases. This is in contrast to the above options, where preexisting test plans are selected for execution.

Typically, this kind of composition is used when expecco is called from a QA system, such as Polarion or HP Quality Centre, where individual "test sets" are composed out of a collection of existing test cases.

Notice, that this may lead to longer startup times, depending on the number of suites found in the suite directory, because suite files there will be opened and searched for matching test cases. If the same set of tests needs to be executed multiple times, it may be agood idea to use the "--saveSuite" option, to have the composed suite saved into a file for later reuse.

Also notice, that this works best, if testcase have unique names or are known by their ID (which is globally unique). If your test management system can provide unique identifiers, these should be used to name your testcases inside the suite (typically, a unique name of the test-case or requirement is used to name corresponding test-cases).
 (These options are only available in release ≥ 2.7)

*'''<code>--suiteDirectory <dirName></code>''' defines the directory, where test suite files are searched for composed test plans. Test cases as specified in one of the options below must be found in one of the files present there. Notice, that the first file which contains a requested test case action will be chosen. Thus, you should ensure, that only one version of each suite is present there. Typically, an up-to-date test suite directory as checked out from the revision control system is specified here. If this argument is not given, test cases are searched in the list of explicitly listed suite files (".ets" arguments).This option also specifies the directory where suites are found for remote execution (see description of SOAP and REST services below).

*'''<code>--suiteTitle <string></code>''' defines the name of the new test plan, which is created dynamically. This is used to control the labels in the generated report files.

*'''<code>--testCaseNames <name-list></code>''' defines the test cases to be included in the test by name. name-list is a list of comma-separated names of the individual test actions. Please only use this option, if your testcases have unique names and are found only once in any suite found in the suite directory. Otherwise, the first suite which contains that name will be chosen (see below for better selection options).

*'''<code>--testCaseFIDs <id-list></code>''' defines the test cases to be included in the test by function ID. id-list is a list of comma-separated UUIDs of the individual test actions. This option is probably not very user-friendly for a human, but allows for a calling program (or script) that the testcase is found even if it has been renamed in the meanwhile (remember that functional IDs are assigned once when an item is created and remain unchanged over the whole lifetime).

*'''<code>--testCaseIDs <id-list></code>''' defines the test cases to be included in the test by version ID. id-list is a list of comma-separated UUIDs of the individual test actions. This option may be very unfriendly for a human user, but allows for a calling program (or script) to ensure that a particular testcase with a particular version is found and executed, even if the testcase has been renamed or modified in the meantime (remember that the ID is changed with every modification). If the same testcase is found in multiple suite files (i.e. in different versions), this will ensure that the correct version will be executed

*'''<code>--saveSuite <fileName></code>''' saves the generated as-hoq suite. Useful if you want to archive such a dynamically generated scatter-gather suite separately from the result file(s), or to automatically construct new suites. Notice that the ".elf" result file will always include the generated ad-hoq suite, so archival of the generated ad-hoq suite is only needed if you generate pdf, html or other non-elf reports.

==== Test Parameters ====

*'''<code>--parameter <fileName></code>''' / '''<code>-P <fileName></code>''' Load a parameter set from a file. A parameter set contains values for a test suite's top environment. This can be either in XML format, as generated with the [[Environment_Editor|"''Save-Parameter-Set''" menu function]], a CSV file, containing key-value pairs or a JSON file containing a JSON dictionary object.Parameter files in either format can be created manually in a text editor, provided by a QM system (such as expeccoALM, HP Quality Center or similar), generated by another controlling program or generated by expecco itself via the "''Save-Parameter''" menu function of the [[Environment_Editor|environment editor]].The parameter file may contain values for a subset of the environment variables. In this case, the values from the parameter file overwrite corresponding values present in the loaded test suite, leaving other values unchanged.

*'''<code>--parameter:<key>=<value></code>''' / '''<code>-P:<key>=<value></code>''' Sets an individual parameter for the next "--execute" argument.If multiple "--execute" arguments are given (i.e. multiple suites are to be executed in sequence), these parameter values are collected and given to the next execution only, and overwrite corresponding values from either a parameter set (see above) or from the suite itself.Thus, it is possible to execute the same suite with different parameters in one command line (see example above). (this option is available with expecco vsn >= 2.10)

==== Test Execution via Scripting ====
*'''<code>--scriptFile <fileName></code>''' read and execute a script from a file (see scripting below).

==== Reporting ====

*'''<code>--verdicts</code>''' Send execution and result info in human readable format to the stderr output. (see [[#Verdicts Example|example below]].)

*'''<code>--logFile <fileName></code>''' Used to change the name of the generated log file, where stderr is written to. This is only useful if running in server mode.

*'''<code>--exitCode <n></code>''' Defines the exit code to be used independent of the test outcome. The default is 0 (zero) if all tests pass, and non-zero when they do not. However, some calling programs (make/jenkins,...) may misinterpret this exit code and treat the whole job as non-executable. Use this flag to prevent this. It is still possible to change the exitCode for a particular outcome by adding one of the following options after this option.

*'''<code>--exitCodeOnFail <n></code>''' Defines the exit code in case any test ends with a test-failure status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute. This option also changes the exitCodeOnError and exitCodeOnInconclusive values (see below), unless explicitly defined by those options.

*'''<code>--exitCodeOnError <n></code>''' Defines the exit code in case any test ends with a test-error status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute. This option also changes the exitCodeOnInconclusive values (see below), unless explicitly defined by that option.

*'''<code>--exitCodeOnInconclusive <n></code>''' Defines the exit code in case any test ends with an inconclusive status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute.

*'''<code>--elfReportFile <elfFilename></code>''' Writes a report in expecoo's native XML logfile format. The report contains a lot of detail information and could be processed by an XSLT processor or a similar tool. It also contains enough additional information about test plans and actions so that expecco can redisplay the activity log tree from this file. The generated file can be opened directly via the command line ("expecco <file>.elf") or by double clicking on the elf-file in the operating system's desktop.

*'''<code>--csvReportFile <csvFilename></code>''' Writes a summary report in CSV format. Each row consists of: 
** ''TESTSUITE'' - the filename
** ''TESTPLAN'' - the test plan
** ''TESTCASE'' - the test case
** ''VERDICT'' - the test result; one of SUCCESS, FAILED, ERROR or INCONCLUSIVE
** ''INFO'' - additional info in case of failure
:Additional pseudo verdicts such as STARTTIME, ENDTIME etc. are written. A typical CVS output file can be found in the [[#CSV File Example|examples]].

*'''<code>--textReportFile <textFilename></code>''' Writes a summary report in a human readable textual format. A typical text output file can be found in the [[#Textual File Example|examples]].

*'''<code>--xmlReportFile <xmlFilename></code>''' Writes a report in XML format. The report contains a lot of detail information and could usually be processed by an XSLT processor or simular tool. A typical XML output file can be found in the [[#XML File Example|examples]].

*'''<code>--pdfReportFile <pdfFilename></code>''' Writes a summary report in pdf format.

*'''<code>--htmlReportFile <htmlFilename></code>''' Writes a summary report in html format.

*'''<code>--junitReportFile <htmlFilename></code>''' Writes a summary report in a junit compatible XML format. Useful, when expecco is to be started by jenkins or similar driver programs.

*'''<code>--polarionReportFile <htmlFilename></code>''' Writes a summary report in an XML format which is especially suited for the Polarion QM tool. The structure of the generated XML is the same as with the junit format above, but a slightly different time format is used.

*'''<code>--reportTemplateName <name></code>''' Use the given report template (must be an element inside the test suite) for the following "--xxxReportFile" argument. If no such argument is given, the default template as defined in the suite is used.

==== Services ====

*'''<code>--server</code>''' Starts expecco in server mode. This combines the "''--service''", "''--infoService''" and "''--remoteControlService''" flags. All of those services as described below are started with that single command line argument.

*'''<code>--service</code>''' Starts expecco in server mode. In this mode, HTTP-SOAP and HTTP-REST requests can be used to remote-control expecco's execution; especially, to execute and monitor tests, and upload results. The most obvious use for this is for expecco to act as an execution host (test slave) for an expeccoALM or Polarion server. However, because standard protocols are used, this may also be used to interface the execution engine to many other QM management or automation systems (e.g. HP Quality Centre). The interface is described below.

*'''<code>--infoService</code>''' Provide an additional info service which allows for monitoring and control of an expecco server via a web browser (server mode only).

*'''<code>--remoteControlService</code>''' Provide an additional service to interact with a running test. Dialog requests, single stepping, starting, pausing and stopping of tests is possible via remote REST requests. This service is used by the Android remote control app, which is available upon request (server mode only).

*'''<code>--port <portNr></code>''' Used to change the HTTP and SOAP port numbers, when running in server mode. The default is 9090 (server mode only).

*'''<code>--scripting <portNr></code>''' Enable scripting (remote control via Telnet ascii interface) on portNr ([[#Scripting Example|see more below]]).

*'''<code>--allowHost <hostName></code>''' Allow hostName to connect to the scripting port. Repeat for multiple hosts (see more below).

==== Utility Functions ====

*'''<code>--diff <file1> <file2></code>''' Print differences between two test suites. This can be used eg. to automatically generate log messages for a revision control system (please read the section on "Integration with Source Code Management System" below). (This function is only available in release ≥ 2.7)

=== Command Exit Status ===

*0 - all tests passed

*>0 various other errors (command line, file not found, etc.)

*101 - at least one test failed (FAIL status). This exitCode can be overwritten by a command line argument.

*102 - at least one test was inconcusive (INCONCLUSIVE status). This exitCode can be overwritten by a command line argument.

*103 - at least one test lead to an error (ERROR status). This exitCode can be overwritten by a command line argument.
 
The diff option returns 0 if the compared suites are the same, or 200+n, (where n is the number of differences) otherwise.

== Sample Outputs ==

The following output files were generated by executing the test suite from the file:
:"C:\Programme\exept\expecco\testsuites\projects\Example.ets"
which contains a single test plan named:
:"Example Testplan"
which contains three test cases named:
:"Test1"
:"Test2"
:"Test3-Should fail"
of which the first two are supposed to PASS and the last one generates an ERROR.

All timestamp information is written in ISO8601 format.

Be reminded that the following reports are condensed reports, which only contain a subset of the information contained in expecco's native ".elf" file format. The "elf" file contains all of the execution, trace and data-flow information and the original suite as executed. "elf"-files can be reloaded at any time into the expecco UI and the test be reexecuted. Also, any of the other reports can be regenerated, posyibly with different report options (i.e. detail).

Thus it is highly recommended that these "elf" files are archived after a test run, in addition to any of the condensed report files (eg. pdf or junit report).

=== CSV File Example ("<code>--csvReportFile</code>" option) ===

By default, entries are separated by ";"-characters. Additional double quotes (") are used to delimit strings with embedded ";" or spaces. Any double quote within such a string is doubled.
CSV is a simple and very common interchange format.
For example, CSV files can be imported into Microsoft Word, Exel and Openoffice (and many other).

TESTSUITE;TESTPLAN;TESTCASE;VERDICT;INFO
;;;StartTime;2008-10-31T08:57:13.689
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test1;PASSED;
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test2;PASSED;
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";"Test3 - Should fail";ERROR;
;;;EndTime;2008-10-31T08:57:18.746

=== XML File Example ("<code>--xmlReportFile</code>" option) ===

<SummaryReport>
<StartTime>2008-10-31T08:56:49.774</StartTime>
<TestSuite>
<File>C:\Programme\exept\expecco\testsuites\projects\Example.ets</File>
<TestPlan>
<Name>Example Testplan</Name>
<TestCase>
<Name>Test 1</Name>
<Verdict>PASSED</Verdict>
</TestCase>
<TestCase>
<Name>Test 2</Name>
<Verdict>PASSED</Verdict>
</TestCase>
<TestCase>
<Name>Test 3 - Should fail</Name>
<Verdict>ERROR</Verdict>
</TestCase>
</TestPlan>
</TestSuite>
<EndTime>2008-10-31T08:56:55.142</EndTime>
</SummaryReport>

This is not to be confused with the "elf" result file format, which is also XML based, but contains a lot more detail.

Notice also, that the junit report format ("<code>--junitReport</code>" option) is similar in structure but uses different tags.
Junit reports are compatible to reports generated by Java jUnit frameworks.
They can thus be used to generate reports and trends in Jenkins/Hudson and other tools which understand the jUnit report format.

=== Textual File Example ("<code>--textReportFile</code>" option) ===

Test Execution Summary
Start: 2008-10-31 08:56:12.751
TestSuite: "C:\Programme\exept\expecco\testsuites\projects\Example.ets
TestPlan: Example Testplan
Test 1 ....................... PASSED
Test 2 ....................... PASSED
Test 3 - Should fail ......... ERROR
Finish: 2008-10-31 08:56:18.009



=== Verdicts Example ===

the "<code>--verdicts</code>" option generates a simple trace on the standard error (to be redirected into a file):

C:\selftest\commandLineArgs> expecco --noBanner --noTray --verdicts
--parameter paramesForTest.xpar --execute parameterTest.ets 
Expecco [info]: start testSuite "parameterTest.ets"...
Expecco [info]: using parameters "paramesForTest.xpar"...
Expecco [info]: start testPlan "Test Parameters From CommandLine"
Expecco [info]: start testCase "Validate Parameters"
Expecco [info]: done testCase "Validate Parameters"; STATUS=PASSED
Expecco [info]: done testPlan "Test Parameters From CommandLine"; STATUS=PASSED
Expecco [info]: done testSuite "parameterTest.ets"; STATUS=PASSED

== Integration with Quality Managament and Automation Tools ==

=== Integration with Jenkins ===

To have expecco tests being executed automatically by Jenkins, take the following example as a guideline. This is a real world setup, taken from our own setup within eXept.

# Create a test job, which is triggered by a successful build (or a change in the test suite repository)
# Check the "Block Build while prerequisite Jobs are Active" flag
# Check either the "Trigger from Source Code Management" or the "Trigger from other Job" flags
# Check "Abort build if it is Stuck" (just to make sure, that a faulty suite does not block Jenkins)
# Check "Fail the Build if Stuck" and give it a reasonable elastic Time-out Strategy (we use 300% of the last 10 builds, to make sure a longer execution time due to more test cases will not be interpreted as a stuck, and an extra timeout of 30 minutes. The timeout is very generous for the expected execution time of a few minutes).
# Check "Run xvnc during Build" to allow for monitoring, what is going on. This is also required, if the test needs a UI.
# Define the "Build Procedure" as "Execute Shell Script" (Unix/Linux) or "Execute Batch Job" (Windows)
# Enter a build procedure similar to the ours, which is:
#::<code>cd exept\expecco\application
#::del *.junit
#::expecco.com --noBanner --exitOnInternalError --noTray \
#::::--jUnitReportFile selfTestResult.junit \
#::::--execute ..\projects\expecco\eXpeccoSelfTest.ets
#::expecco.com --noBanner --noTray \
#::::--jUnitReportFile CommunicationWithExpeccoNETResult.junit \
#::::--execute ..\projects\expecco\CommunicationWithExpeccoNET.ets</code>
#:The details (especially paths and names) will of cause be different in your setup. The above uses the relative paths as it first changes the current directory to where the previous build has compiled the executable, which will of course not be the case in your setup.
# Define a "Post-build Action"
# Check "Publish Junit Test Results"
# Enter a path expression to declare the location of the resulting reports. Here, we used:<PRE>exept\expecco\application\*.junit</PRE>
# Check the "Publish Test Attachments" flag, so the results will be presented in the Jenkins management console

That's it! Because expecco has been told to generate jUnit compatible report files, we can use Jenkins' existing jUnit support. However, the jUnit xml format does not support the full range of information which is present in the native expecco result files (especially the activity log and pin value information is not included). Therefore, it is a good idea to also generate a regular ".elf" (expecco log file) and add it to the archived build artefacts.

=== Integration with expeccoALM ===
Expecco and ExpeccoALM (formerly called "''expeccoNET''") have been originally designed to work together. Therefore, only a minimum setup is required:
# ensure that an expecco test execution slave is running on each test host (server farm, virtual machines, etc.). Depending on the operating system, this is either done by installing expecco as a service (Windows), or by adding appropriate startup actions to your "init.d" files (Unix).
# define the test host(s) in expeccoALM.
# (optionally) define the devices available and attached to the execution slave machine in expeccoALM

ExpeccoALM will ask the expecco slaves about their operating system environment. So jobs will be automatically executed on matching CPU/OS machines. However, if tests require special resources (devices) to be attached, these must be defined and listed in expeccoALM as well. If your test has corresponding resource-requirements defined (see resources/inventory), expeccoALM will both ensure that the test will execute on the correct machine, and also reserve the resource during the execution. Also, test scheduling, if defined to be automatic, will be optimized to minimize resource usage, and to ensure that a higher number of tests can be executed in parallel.

=== Integration into a SOA Infrastructure ===

For this, expecco should be started on the test host(s) in so called "slave" mode.
In this mode, expecco awaits for execution commands via SOAP or REST, executes tests in the background and returns status information (progress) and results (reports).

Because tests may execute for a long time (hours or even days), the execution is performed asynchonously; first, the test has to be downloaded to the slave, then execution started. The start-command returns a ticket, which is a test-run-identifier, by which the execution progress can be queried (polled) while the test is running. Finally, a "finished" status is returned, upon which the result can be aquired via another service call.

Multiple such test slaves can be started on multiple machines, and each test slave may (if required) execute multiple tests in parallel (although this is usually limited to one, to avoid conflicts when external resources are accessed).

To start expecco in slave mode, use the command line:
expecco --service

or, if the default port (9090) is not available, use:
expecco --service --port 9090

The service interface is described below; typically, you can talk to expecco via:
http://localhost:9090/expeccoService
or:
http://localhost:9090/expeccoService/rest

The SOAP wsdl is returned via:
http://localhost:9090/wsdl/ExpeccoSOAPService.wsdl

and - if the inforService is also running - general status information with:
http://localhost:9090/info

=== Integration with HP Quality Center ===

This is described in the [[ HP Quality Center Plugin ]] document.

=== Integration with Polarion ===

This is described in the [[ Polarion Plugin]] document.

== Integration with Source Code Management Tools ==

=== Background Info on what is Contained in a ".ets" File ===

Expecco stores testsuites in a file with '.ets' extension (which stands for: "''Expecco-Test-Suite''") and result logs in '.elf' files (stands for: "''Expecco-Log-File''").
These are technically zip files - i.e. a bundle of individual files which can be extracted with the common zip command line tool (winzip under Windows systems, zip/unzip under Unix systems).

For example, "<code>unzip -l foo.ets</code>" lists the individual components, of which especially the block descriptions and attachments may be of interest.

Notice, that you have to be careful when ets-files are bundled with zip manually: for various consistency checks, expecco generates a validation signature of the components and saves this as an additional file inside the .ets file.
This signature file must be preserved and it must be consistent with the other zip-components. In effect, this means that an ets can only be constructed from the very same components, using the very same signature file as were extracted before. Otherwise, expecco refuses to load the ".ets" file later.

=== Version Management of ".ets" files ===

Unless a QA system like "expeccoALM" is used, ets-files can be stored and maintained in any other source code management (SCM) system, for example, CVS, SVN, hg/Mercurial, git, Perforce etc.
Make sure to store the .ets as binary file, and/or disable source expansion of version tag lines (for example, "$Header" or "$Id" in CVS). Consult your particular SCM system's documentation on how this is done.

As an alternative, it is possible to unzip the ets into individual components, store them separately, and zip them back into an ets, when a previous version is extracted from the SCM system. However, you must be careful to preserve the contents exactly as is, including the signature and other meta data, and not mix versions. I.e. all individual component files must be checkedIn/out in sync and as a group - it is not possible to update individual files from previous versions. The reason is that action blocks are referred to by their versionID, and these IDs will certainly be inconsistent, when previous versions of individual action blocks are mixed into another version's suite.

If, for whatever reason, you must checkin individual action blocks, we highly recommend to check in BOTH the bundled ets (and use that for later test execution), AND check in the individual components, and use only those for meta actions, such as comparison, documentation or other administrative tasks.

=== Generating Diff Lists or other Version Information ===

Many source code management systems allow for hook-scripts to be added to checkin/checkout actions, and/or to redefine the command to be used for diff-list generation.

For example, in the SVN system, an external diff tool can be defined. You could write a little shell or batch script, which calls expecco with the "<code>--diff</code>" option which is described above. Thus, you would get meaningful diff output even from checked in ets-bundle files.

The "<code>expecco --diff</code>" option is also useful as a command line tool to get diff lists - even if your SCM system does not allow for such automatic hooks.

== Scripting ==

Expecco can be scripted either by reading a script from a file or remote controlled via a telnet like command-line interface.
This is useful to execute complex test scenarios and meta tasks, to create or manipulate test suites automatically and for self-testing expecco by using another expecco to control its GUI.
It can also be used to execute and automate more complex scenarios without using expeccoALM.
 Example uses are:
* Sequentially load and/or execute all suites found in a folder, reimport libraries, save the updated suite
* Construct new suites by merging/selecting tests from other suites
* Bulk renaming, commenting, attributing etc.
* Change attachments inside a number of suites
* Controlling an application or web interface (via a GUI plugin) and saving a sequence of screen shots

By default, the scripting interface expects expressions in JavaScript syntax (but with a Smalltalk object model),
similar to the language used for elementary block definition. However, the language can be changed to Smalltalk syntax via a "~" directive.

=== Script File Example ===

To control expecco via a scriptfile, use the "<code>--scriptFile <filename></code>" command line argument, where <filename> must be a file containing JavaScript expressions.

For example, the following script file named "run3Suites.js" may contain the code:
<PRE>
// Example for an automatic expecco script.
// (loads and executes a number of test suites)
//

// to enable debugging in case of an error.
// STXScriptingServer.errorDebugging(true);

var files = [
"foo.ets",
"bar.ets",
"baz.ets",
];

Expecco::ExpeccoPreferences.current.automaticReimportOnLoad(true);
Expecco::ExpeccoPreferences.current.checkForReimportableImportsOnLoad(true);
Expecco::ExpeccoPreferences.current.checkForAnchestorOnAutomaticReimport(false);
// Expecco::ExpeccoPreferences.current.libraryPath(importPathes);

// --------------------

function executeTestPlan ( aTestPlan ) {
Stderr.nextPutLine("executing testplan "+aTestPlan.name()+"...");
resultList = aTestPlan.execute();
Stderr.nextPutLine("done.");
}

function runSuite(suiteFile) {
var loadedProject;

Stderr.nextPutLine("loading "+suiteFile+"...");
expecco.loadProjectFromFile(suiteFile);
loadedProject = expecco.project();

if (loadedProject == null) {
Stderr.nextPutLine("failed to load library "+suiteFile+".");
Smalltalk.exit(1);
} else {
loadedProject.allTestPlansDo( executTestPlan );
}
};

files.do(runSuite);
</PRE>

And can be executed with:

expecco --scriptFile run3Suites.js

for windowless operation, use the "<code>--noWindow</code>" command line argument.
To speed up the startup, you can turn off the loading of plugins, with a "<code>--noPlugins</code>" argument (and possibly load any required plugins explicitly via additional plugin arguments).
Finally, enable debug messages with a "<code>--debug</code>" argument.
Thus, the recommended options for scripting are:

expecco --debug --noPlugins --noWindow --scriptFile run3Suites.js

of course, this command line can be put into a shell (or batch) script file, and then executed with a single word command.

=== Telnet Scripting Example ===

The remote scripting service is enabled when a "<code>--scripting</code>" command line argument is given.
By default, the service only accepts connections from the local host (for security reasons). Using the "<code>--allowHost</code>" option, more hosts can be gained access to the scripting feature - but be aware, that this opens a potential security hole, as all of the internal functions can be accessed via the scripting system (and this includes the possibility to write files and call operating system services with the access rights of the one who started the scripting server).

When used with a remote script connection (telnet),
additional connection- and execution related commands are introduced by lines starting with the "~" (tilde) escape character (similar to telnet).
For example, "~." (tilde-period) is used to close the connection.
Press "~?" (tilde-question) for help.

The following is a trace of a typical scripting session (user input in bold):

c:\programs\expecco> expecco --scripting 8008
c:\programs\expecco> ... expecco now running in the background with GUI ...
...
c:\programs\expecco> telnet localhost 8008
Welcome to Expecco (Type ~? for help)
> println(expecco);
an Expecco::Browser
> expecco.menuNewProject();
...expecco performs the new-function from its menu...
> expecco.loadProjectFromFile("C:\Users\cg\testsuites\webedition\projects\BearerTest.ets");
...expecco loads the testSuite...
> expecco.close();
> ~.
Lost Connection.
c:\programs\expecco>

You can also start a scripting session without an initial expecco browser window:

c:\programs\expecco> expecco --noWindow --scripting 8008
c:\programs\expecco> ... expecco now running in the background without GUI ...
...
c:\programs\expecco> telnet localhost 8008
Welcome to Expecco (Type ~? for help)
> println(expecco);
an Expecco::Browser
> expecco;
> ~v+ // turn result-printing on
> expecco
an Expecco::Browser
> ~v- // and off again
> expecco.loadProjectFromFile("~/SomeTest.ets");
...expecco loads the testSuite...
> var blk = expecco.project.elementWithName("My Action");
> blk.name("My Fun Action");
> expecco.saveProjectToFile("~/ModifiedTest.ets");
> expecco.close();
>~.
Lost Connection.
c:\programs\expecco>

== Scripting API Overview ==

A few objects are predefined by name; among them are "''expecco''", which refers to the browser itself (i.e. the UI) and "''environment''", which refers to a collection of variable bindings (this is a dictionary of interpreter variables - not to be confused with a variable environment as known inside an expecco activity block).
 New variables can be defined with a "<code>var <name>;</code>" statement. For example:
<CODE><PRE>
var ws;

ws = new ExpeccoWorkspaceApplication;
ws.open();
ws.close();
</PRE></CODE>

==== expecco Object ====

The variable named "''expecco''" refers to the opened GUI-object, which represents the expecco application itself.

===== Expecco Functions =====

*'''project()''' the current project
*'''currentApplication()''' the current page (initially, there is only one)
*'''currentTreeApplication()''' the current tree sub-application

*'''selectModelItem( anItem )''' select an item and open an editor for it
*'''selectedModelItems()''' returns a collection of selected items
 

===== Menu Functions =====
These execute the underlying menu functions (as if clicked by the user).

*'''menuNewProject()''' creates a new testSuite
*'''menuOpen()''' opens a dialog requesting a testSuite
*'''menuExit()''' closes the expecco application

*'''loadProjectFromFile(fileNameString)''' load a testSuite
*'''saveProjectToFile(fileNameString)''' save the testSuite
*'''selectTestPlanWithName(testPlaneNameString)''' select a testplan item by name
*'''selectTestPlanWithFunctionalId(uuid)''' select a testplan item by uuid

*'''testSuite()''' retrieves the testSuite object (see below)
 

===== Test Suite (Project) Functions =====
the project as returned by the above "project()" function provides access to its elements:
 (see also [[ Expecco API#Test Suite Project Functions]])

*'''authorName()''' get the author name string
*'''authorName(aString)''' set the author name string
*'''versionString()''' get the version string
*'''versionString(aString)''' set the version string
*'''projectsWorkingDirectory()''' the directory, where attachments etc. are found
*'''ensureEnvironment()''' an instantiated environment (concrete values). See below.
*'''elementWithName( nameString )''' returns a matching element or null if not found
*'''elementWithId( aUUID )''' returns that element or null if not present. (create the UUID with "<stringConstant>.asUUID" )
*'''elementWithFunctionalId( aUUID )''' returns that element or null if not present
 

==== Environment Object ====

Environment objects are used to store key-value bindings for expecco variables. Environments form a hierarchy, where values are searched for in an environment's parent environment, if not present. This hierarchy follows the containing compound activity chain up to the project (= test suite) environment.
Additional temporary environments are kept by the executor and the browser, to keep temporary values for a single execution's or a single session's lifetime.

*'''at(key)''' retrieves a value, given the name of the entry. Raises and error if no variable exists by that name.
*'''at_ifAbsent(key, default)''' like above, but returns default if no variable exists by that name (instead of raising an error).
*'''includesKey(key)''' true if a variable by that name exists, false otherwise.
*'''at_put(key, value)''' store value as variable named key. Raises an error, in an attempt to change a readOnly variable
*'''environmentDescription()''' returns the environment's description. This describes types, default values and read/write attributes per entry.
 

==== EnvironmentDescription Object ====

This is a collection of entries which describe variables of an environment. It does only hold the description, not the bindings themself; i.e. it contains the information required to instantiate an environment. EnvironmentDescriptions inherit from OrderedCollection and therefore entries are accessed via "at:" using a numeric index from 1 to the environmentDescription's size.

Entries (as per variable) provide the following protocol:

*'''name()''' the name of the variable
*'''isReadOnly()''' true if readonly
*'''defaultValue()''' the initial value, assigned when the environment is created
*'''datatype()''' the type of the variable
*'''comment()''' description
 

== Remote Controlling and Monitoring Expecco ==

Expecco itself can be automated by various mechanisms:

* via command line arguments (described in [[ #Command Line | "Command Line"]] above)

* via script files (see [[ #Script File Example | "Script File Example"]] above)

* via the telnet interface (see [[ #Telnet Scripting Example | "Telnet Scripting Example"]] above)

* via standard RPC mechanisms, such as SOAP or REST.

Especially the RPC mechanisms are useful to integrate expecco into the company test infrastructure.
Such interfaces are meant for programmatic control of an expecco slave from quality management, application life cycle and other scheduling tools.
Our own companion product, ExpeccoALM and third party tools, such as Polarion use these service interfaces.

Notice, that for integration into a Jenkins infrastructure, command line arguments or scripts may be a more cost efective means to control automated expecco testruns.

=== Expecco as a Slave Node in a Test Lab ===

The service interfaces are useful to control unmonitored slave machines in the network, among which expecco test execution jobs are scheduled by another program. ExpeccoALM and other quality management tools use these to initiate test runs in a test server farm.
For this, the basic operations "download of a suite", "execute a suite" and "requesting execution results" are available as service calls.

Both SOAP and REST services are available, if expecco is started with the "''--server''" argument.
An optional "''--port''" argument allows for the HTTP port to be changed from the default (9090) on which expecco is listening.

For debugging and testing, the service can be also be started from the interactive UI, via expecco's main menu (in the "''Extras''" - "''Web-Services''" - "''Start / Stop''" menu items).

These services use HTTP requests as transport layer.

==== Expecco SOAP Service Interface ====

This accepts SOAP requests, via the URL "<code>/expeccoService</code>". I.e. the default URL is "<code>host:9090/expeccoService</code>".
A partial WSDL spec can be aqcuired from the running service via "<code>host:9090/wsdl/ExpeccoSOAPService.wsdl</code>" (partial, because it is currently not does not contain complete type information).

The service entries are:

===== Loading and Executing a Suite =====

The execute request is the main service entry. It passes the suite and also optional parameters.

The test suite can be bade available to expecco either by passing it with the request (as base64 CDATA), or by passing a URL from which expecco can fetch the suite iteslf.

The execute call contains the following fields:

<message name="expecco_executeProject_v5_Request">
<part name="id" type="UUID"/>
<part name="testSuiteId" type="UUID"/>
<part name="dataSource" type="xsd:string"/>
<part name="dataSourceUri" type="xsd:string"/>
<part name="environment" type="xsd:arrayType"/>
<part name="testplans" type="xsd:arrayType"/>
<part name="resources" type="xsd:arrayType"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

and responds with:

<message name="expecco_executeProject_v5_Response">
<part name="result" type="xsd:string"/>
</message>

This call starts execution, and immediately returns a response, which consists of an identifier.
This identifier can later be used to ask expecco about the execution status. As a test may take a long time to finish,
it is useful to poll via status requests from time to time, to see if the execution has finished and to get progress status.

The parameters are:

* id - mandatory; a ticket ID; this should be a UUID-string, to avoid possible conflicts
* testSuiteId - mandatory; the UUID of the suite to execute. See below for details about download optimizations
* dataSource - optional; if present, this should contain the whole ets-file's contents as a Base64 encoded CDATA string
* dataSourceUri - optional; if present, this should be the URI from which expecco shall fetch the suite. See below for details
* environment - optional; top-level environment variable values. This can be used to provide alternative initial values for variables in the top level variable environment (the "Project-Environment")
* testplans - optional; a list of UUIDs of testplans to execute. If not present, all top-level testplans are executed
* resources - optional; a list of resources to be used by the test (see expeccoALM resource description)
* optionalParameters - optional; an array containing additional parameters as key-value elements.

The "optionalParameters" field:

A list of key-value elements (i.e. must have an even number of elements, of the form [k1 v1 k2 v2 ... kN vN] ).
Each key is an xsd:string, each value's type depends on the key, but all of them are currently also strings.
The list of supported parameters is open for future extension of the interface. Currently, the following are recognized:
* [ "generateLog" xsd:boolean ] - the boolean arg must be "true" or "false"
* [ "generatePDFReport" xsd:boolean ] - boolean arg, must be either "true" or "false"

The "testplans" field:

this allows selective execution of individual test plans and also individual test cases (from within a test plan) from the suite.
If not present, all test plans as present in the suite are executed.
If present, the testPlans parameter must be an xsdarray of pairs (i.e. each array element is again an xsdarray with 2 elements).
Each top level element describes one testplan to be executed. The first element of each being the testplan's UUID, the second another array, listing the testcases by UUID.
For example, if the suite contains three testplans, named "a", "b" and "c", with plan "a" having id-a and "b" having id-b as UUID.
A testPlans argument might look like:
<pre>
[
[ id-a ]
[ id-b [ id-tcb-1 id-tcb-2 ] ]
]
</pre>
and specify that testplan "a" should be executed fully (i.e. all test cases), and only the testcases tcb-1 and tcb-2 are to be executed from testplan "b".

The "environment" field:

-- to be described --

The "resources" field:

-- to be described --

The reply consists of the ticket-id, which has to be passed in further status requests.

===== Loading Only =====

It is also possible, to download a suite without execution, via the "download" request:

<message name="expecco_downloadProject_Request">
<part name="testSuiteId" type="xsd:string"/>
<part name="dataSourceBase64" type="xsd:string"/>
<part name="dataSourceUri" type="xsd:string"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

<message name="expecco_downloadProject_Response">
<part name="result" type="xsd:string"/>
</message>

===== Download Optimization =====

Expecco remembers downloaded suites in a temporary folder, to avoid repeated transfers of possibly huge test suites.
If a URI is passed (but no base64 encoded data), expecco checks if the suite is already present on the test host,
and will not fetch it again, if already present. If not present, expecco will fetch the suite via a HTTP request from the URI.

If no URI is passed (i.e. both data and dataURI fields are empty), expecco will either respond with an error reply, if not present,
or with an ok response, if already present.

Thus, if you have to pass the suite as data (i.e. there is no file service available, from which expecco could fetch the suite),
it is recommended to first check if a suite is already present (by sending a download request without data) and check for an error return. If no error is reported, the suite is already there and no further download action is required. If there is an error response,
the client should send the suite with another download request, this time with a non-empty data field.

After any successfull download (either via download, or via execute request), the suite can be executed by an execute request without data.

===== Execution by Suite File Name =====

An alternative to downloading suites is to execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.
The executeTestSuiteFile-request is used to execute one of the suites in that directory.

The call contains the following fields:

<message name="expecco_executeTestSuiteFile_Request">
<part name="id" type="UUID"/>
<part name="fileName" type="xsd:string"/>
<part name="environment" type="xsd:arrayType"/>
<part name="testplans" type="xsd:arrayType"/>
<part name="resources" type="xsd:arrayType"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

If successful, a ticketID is returned (same as above execute-request).

===== Status Request =====

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the above execute request.

<message name="expecco_getExecutionInfo_Request">
<part name="ticketId" type="UUID"/>
</message>

<message name="expecco_getExecutionInfo_Response">
<part name="result" type="xsd:string"/>
</message>

A client may have to send multiple "getExecutionInfo" requests, until a "finished" status is returned.
Expecco will keep the generated reports and log files in a temporary folder, until fetched via a getResult request.
This allows for both expecco and the client to be turned off and restarted, without loosing any status information.

===== Result Request =====

Once finished, reports and log files should be fetched from expecco.

<message name="expecco_getResult_Request">
<part name="ticketId" type="UUID"/>
<part name="removeResultBoolean" type="xsd:string"/>
</message>

<message name="expecco_getResult_Response">
<part name="result" type="xsd:string"/>
</message>

After the "getResult" request, corrsponding files are automatically removed from the temporary folder by expecco.

===== Terminate/Abort Request =====

Use this, to abort and terminate an ongoing test execution.

<message name="expecco_killExecution_Request">
<part name="ticketId" type="xsd:string"/>
</message>

<message name="expecco_killExecution_Response">
<part name="result" type="xsd:string"/>
</message>

===== Remove Ticket Request =====

Use this, to tell expecco, that no further interest exists in a ticket.
If the test is still running, it is aborted. If it is about to be started, it will not be.
Any temporary files which might have already been created due to this execution are removed.

<message name="expecco_killExecution_Request">
<part name="ticketId" type="UUID"/>
</message>

<message name="expecco_killExecution_Response">
<part name="result" type="xsd:string"/>
</message>

===== Ping =====

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

<message name="ping_Request">
</message>

<message name="ping_Response">
<part name="result" type="xsd:array"/>
</message>

===== Cleanup of Old Result/Log Files =====

This request can be used to remove all temporary files, especially leftover report- and log files.
This should be used, if a client has crashed, and lost track of

<message name="expecco_cleanupTempFiles_Request">
</message>

<message name="expecco_cleanupTempFiles_Response">
<part name="result" type="xsd:string"/>
</message>

===== Example Wire Protocol Trace =====

Client asks expecco to execute a suite.

<-- HTTP Request to Expecco --
<PRE>

POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 8925
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">

<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_executeProject_v5 xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<optionalParameters xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[6]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">generateReport</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">generateLog</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">runAllTestcasesIfEmptyTestcaseList</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
</optionalParameters>

<testSuiteId xsi:type="UUID">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<testplans
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:arrayType[1]">
<item
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
enc:arrayType="xsd:anyType[2]">
<item
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xsi:type="xsd:string">f71c4700-7477-11df-a41b-00ff7b08316c
</item>
<item
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
enc:arrayType="xsd:anyType[0]">
</item>
</item>
</testplans>
<id xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</id>
<dataSource xsi:null="1"/>
<dataSourceUri xsi:type="xsd:string">http://127.0.0.1:8662/expeccoALM/tentativeObjects/a84b2d96-d133-47db-9fc2-17208b490bfe.a
</dataSourceUri>
<environment
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[22]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Host__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">sr-laptop</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_LoginUserName__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">admin</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_FullUserName__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">. *admin*</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_TestHost__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">127.0.0.1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_UUID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">e5c9cb30-a253-11e4-9f24-c48508c91d3c</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_ID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">d4</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_Name__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Test For Resources and Skills</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_Summary__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string"></item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Run_UUID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">200d93e1-a258-11e4-b9eb-c48508c91d3c</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Run_ID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">r14</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_TestSuite_VersionNumber__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">1</item>
</environment>

<resources
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[28]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute1-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute2-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute2-2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Float</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0.0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 2 eeee</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute1-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
</resources>
</m:expecco_executeProject_v5>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco

<PRE>

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 649
Connection: Keep-Alive

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_executeProject_v5Response xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</result>
</m:expecco_executeProject_v5Response>
</env:Body>
</env:Envelope>

</PRE>

Client asks expecco for execution state

<-- HTTP Request to expecco

<PRE>

POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 635
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfo xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<ticketId xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</ticketId>
</m:expecco_getExecutionInfo>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco (while still executing)

<PRE>

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 2579
Connection: Keep-Alive

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfoResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result>
<executionResultState xsi:type="xsd:string">executingTestSuite</executionResultState>
<currentActivity xsi:type="xsd:string">executing Neuer Testplan</currentActivity>
<pdfReportFileURL xsi:null="1"/>
<summaryResult>
<summaryTestplanExecutionResults xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<summaryTestPlanItems xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<detailString xsi:null="1"/>
<resultActivityState xsi:type="xsd:string">Successful</resultActivityState>
<testplanItemName xsi:type="xsd:string">Neue Aktion</testplanItemName>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanItemExecutionResult</expeccoClass>
</item>
</summaryTestPlanItems>
<testPlanId xsi:type="xsd:string">22623ef0-757d-11df-a41b-00ff7b08316c</testPlanId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanExecutionResult</expeccoClass>
<testPlanName xsi:null="1"/>
</item>
</summaryTestplanExecutionResults>
<testSuiteName xsi:type="xsd:string">Test For Resources and Skills</testSuiteName>
<testSuiteId xsi:type="xsd:string">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestSuiteExecutionResult</expeccoClass>
</summaryResult>
<logFileURL xsi:null="1"/>
<expeccoClass xsi:type="xsd:string">Expecco::SoapExecutionResult::SummaryEncoding</expeccoClass>
<executionProgress xsi:type="xsd:integer">0</executionProgress>
</result>
</m:expecco_getExecutionInfoResponse>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco (after execution)

<PRE>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 2781
Connection: Keep-Alive

.....................
<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfoResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result>
<executionResultState xsi:type="xsd:string">finished</executionResultState>
<currentActivity xsi:type="xsd:string">executing Neuer Testplan</currentActivity>
<pdfReportFileURL xsi:type="xsd:string">http://127.0.0.1:9090/expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.pdf</pdfReportFileURL>
<summaryResult>
<summaryTestplanExecutionResults xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<summaryTestPlanItems xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<detailString xsi:null="1"/>
<resultActivityState xsi:type="xsd:string">Successful</resultActivityState>
<testplanItemName xsi:type="xsd:string">Neue Aktion</testplanItemName>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanItemExecutionResult</expeccoClass>
</item>
</summaryTestPlanItems>
<testPlanId xsi:type="xsd:string">22623ef0-757d-11df-a41b-00ff7b08316c</testPlanId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanExecutionResult</expeccoClass>
<testPlanName xsi:null="1"/>
</item>
</summaryTestplanExecutionResults>
<testSuiteName xsi:type="xsd:string">Test For Resources and Skills</testSuiteName>
<testSuiteId xsi:type="xsd:string">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestSuiteExecutionResult</expeccoClass>
</summaryResult>
<logFileURL xsi:type="xsd:string">http://127.0.0.1:9090/expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.elf</logFileURL>
<expeccoClass xsi:type="xsd:string">Expecco::SoapExecutionResult::SummaryEncoding</expeccoClass>
<executionProgress xsi:type="xsd:integer">100</executionProgress>
</result>
</m:expecco_getExecutionInfoResponse>
</env:Body>
</env:Envelope>

</PRE>

Client fetches the report and log files from expecco:

<-- HTTP Request to expecco (fetch logfile)

<PRE>
GET /expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.elf HTTP/1.1
Connection: Keep-Alive
User-Agent: Mozilla/3.0N
Host: 127.0.0.1:9090
Accept-Encoding: chunked
Accept-Language: en,*
Accept-Charset: iso-8859-1,*,utf-8
Accept: */*
</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: application/x-expecco-logfile
Content-Length: 12690
Connection: Keep-Alive
Cache-Control: max-age=86400
Last-modified: Thu, 22 Jan 2015 17:32:50 GMT

... a lot of elf-file data ...
</PRE>

<-- HTTP Request to expecco (fetch pdf report)

<PRE>
GET /expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.pdf HTTP/1.1
Connection: Keep-Alive
User-Agent: Mozilla/3.0N
Host: 127.0.0.1:9090
Accept-Encoding: chunked
Accept-Language: en,*
Accept-Charset: iso-8859-1,*,utf-8
Accept: */*
</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 29768
Connection: Keep-Alive
Cache-Control: max-age=86400
Last-modified: Thu, 22 Jan 2015 17:32:51 GMT

... a lot of pdf data ...
</PRE>

Client releases ticket (so expecco can remove the temporary data)

<-- HTTP Request to expecco

<PRE>
POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 627
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_removeTicket xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<ticketId xsi:type="UUID">ad8011e1-a25c-11e4-b9eb-c48508c91d3c</ticketId>
</m:expecco_removeTicket>
</env:Body>
</env:Envelope>

</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 614
Connection: Keep-Alive

.....................
<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_removeTicketResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result xsi:type="xsd:boolean">true</result>
</m:expecco_removeTicketResponse>
</env:Body>
</env:Envelope>

</PRE>
===== Example Session Using "<code>wget</code>" =====

Using "wget" with SOAP is possible, but a little complicated, because correct SOAP requests have to be constructed, and ticket-numbers be extracted from responses. It is much easier with the REST service.

See below for a description.

==== Expecco REST Service Interface ====

This accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

The REST service supports the same set of operations as the SOAP service described above, but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are all HTTP-GET requests, possibly with attached JSON encoded argument data.
The operation is determined by the URI: the last component is the operation name to be executed.

See details [[ Starting_expecco_via_Command_Line/rest | "expecco rest service interface"]].

=== Expecco Remote Control REST Service Interface ===

A secondary REST service is available to interact with a running test.
This service is used by the "expecco remote control App", which is available for Android devices (tablets and cell phones).

This accepts REST requests, via the URL "/remote". I.e. the default URL is "host:9090/remote".
A description of the supported REST calls can be aqcuired from the running service via "host:9090/remote/protocolInfo".

When this service is active, the standard Dialog requests (input boxes, with "OK"/"Cancel" buttons) will also be presented on the remote controlling app, and can be answered either on the PC-screen OR on a remote android device.
An obvious application of this is when the test system (hardware) needs manual interaction and you have to leave the workplace for this. Here, it is very convenient to be able to answer questions like "Insert Cable X and press OK to proceed" from a mobile device. Avoiding the need to walk back to the workplace to click on the "OK" button.

=== Expecco Short Status Information Service ===

This is a very simple HTTP service, which delivers a single page with a status overview.
This service is started when the "<code>--infoService</code>" or "<code>--server</code>" command line arguments are present.

This accepts HTTP requests, via the URL "/info".
I.e. the default URL is "<code>host:9090/info</code>".

The main use of this service is to quickly check the status of a testslave from a remote webbrowser,
without a need for a more complicated SOAP or REST service client.

Back to [[Online_Documentation#Topic:_Execution | Online Documentation]]

Starting expecco via Command Line/en

2017-04-02T12:49:35Z

Ab: /* Expecco REST Service Interface */

== Introduction ==

expecco can be started manually via the command line, by batch or shell scripts or automatically via the crontab (Unix) or scheduled tasks / services (Windows) mechanism of the operating system. Thus, you can have tests to execute unattended and without GUI "overnight". This is also the method to integrate expecco with other quality tools, such as Jenkins, HP-Quality Center, Polarion, expeccoALM etc.

Command line options allow for test suites to be loaded, executed and result files being generated without requiring user interaction.

In addition to the above, expecco can also be started in a slave mode as a service, to wait for incoming test-run request from a QM system, such as expeccoALM or Polarion. Expecco can respond to request via SOAP or REST calls to load, execute and report test suites. The expeccoNET automation environment assumes that expecco is already running on each slave host, and each has been started with a "--server" command line argument. It uses HTTP+SOAP/REST to communicate with those expecco slaves by default.

In this later "slave mode", expecco is installed to run as a daemon process (under Unix) or as a service (under Windows), and will be automatically started by the operating system, when it boots. The details of how it is installed vary between operating systems: under Unix, it needs to be registered in the init-tab-folder, under Windows it needs to be installed as a Windows service.

== Command Line ==

If expecco is started without command line arguments, it will open up showing the initial welcome screen. The same behavior as if started via the desktop.

With a single file argument, expecco will read a test suite from the given file and open an editor window on it (but will not execute it).

'''expecco <testsuite filename>'''

This is the same behavior as if a test suite file (.ets) is dropped onto the expecco icon via the desktop.

The simplest command line to execute a test suite is:

'''expecco --execute <testsuite filename> ...'''

:<testsuite filename> is the test suite's filename, as saved from within the expecco GUI application. This should be a saved ".ets" testSuite file. If more than one test suite filename is given, each is processed in sequence. All top-level test plans as found in the test suite(s) are executed (see below for more options).

:By default, the overall execution outcome is returned by the command's return value (exit code), which is
::0 - all PASSED
::non-zero - any ERROR, FAILURES or INCONCLUSIVE items.

The return value is useful if expecco is started via a makefile, or from jenkins for example. If the caller needs a different exit code, use one of the exitCodeOnXXX options as described below. This is useful to avoid a ''make'' or ''jenkins'' process from stopping.

To get a list of available options, type:
'''expecco --help'''

=== Command Line Options ===
Command line options are handled at two places: the runtime system (Smalltalk/X VM) and the expecco application itself.
When expecco is started, the VM is first to look for command line arguments and processes any of the VM options, until
a non-VM option is encountered. It passes the remaining options to expecco's main entry.
Thus, any option which is given after the first non-VM option will not be handled by the VM, but by expecco. Therefore, no VM options should be placed after the first non-VM option. VM options are marked as "''VM option''" in the list below.

Also, some options are specific to the operating system, on which expecco is executed. These are marked as "''Windows''", "''Linux''" etc.

=== Recommended Command Line Options ===

To start expecco on an existing test suite, use:

'''expecco <testsuite filename>'''

this is also the way expecco is started, when a test suite file is double-clicked on the Linux or Windows desktop, or when a test-suite document is dropped onto the expecco icon.
The above opens the expecco GUI and loads the given test suite initially. However, it does not automatically execute any test.

To execute a suite, add a "'''--execute'''" argument (or in expecco 2.10, "-E"), as in:

'''expecco --execute <testsuite filename>'''

You will notice, that expecco shows a banner intitially; this can be disabled with a '''--noBanner''' option. Also, under windows, a small tray icon is shown in the lower right, which provides a controlling UI. This is disabled with '''--noTray'''.

Finally, as mentioned before, the test's outcome is reported via the exit code. If you want a little more information on the status of individiual test cases, use a '''--verdicts''' option.

This makes the following a good start for your command line:

'''expecco --noBanner --noTray --verdicts --execute <testsuite filename>'''

or, if you want to use a special parameter-file, to provide values for (some of) the project-variables:

'''expecco --noBanner --noTray --verdicts --parameter <param-file> --execute <filename>'''

Parameter files are XML, CSV or JSON-files containing key-value pairs. They are usually created by saving an environment from within the expecco GUI (see [[Environment Editor]]).

All of the above command lines opened an expecco UI window.
To execute a suite without GUI, add a "'''--noWindow'''" argument.

To compose "scatter-gather" test cases from possibly multiple suites, found in a directory use:

'''expecco --suiteDirectory <dirName> --testCaseNames "T01,T02,T05" --execute'''

or, to explicitly specify the suite-files where test cases are taken from, use:

'''expecco --testCaseNames "T01,T02,T05" --execute <suiteFile1>.ets <suiteFile2>.ets ...'''

Finally, to get a report, add a "'''--xxxReportFile <fileName>'''" argument, as in:

'''expecco --noBanner --noWindow --noTray --verdicts --parameter <param-file>''' \
''' --pdfReportFile result.pdf --execute <filename>'''

All options are described in more detail below.

=== Executing Multiple Test Suites in Sequence ===

It is possible to run multiple (possibly different) test suites with one command line to reduce startup and project loading times.
For this, provide multiple "--execute <filename>" arguments to the command line, as in:

'''expecco --execute <suiteFile1>.ets --execute <suiteFile2>.ets ...'''

with this command line, expecco first executes the toplevel testplan(s) from "suiteFile1.ets", then those from "suiteFile2.ets". All parameters (i.e. top-level variable values) will be taken from within the corresponing suite file.

To change individual parameters, use "--parameter:key=value" arguments before the corresponing --execute argument. For example, to execute the same suite with different parameters, use a command line like:

'''expecco --parameter:device=samsung --execute mobileTest.ets''' \
''' --parameter:device=nexus --execute mobileTest.ets'''

=== Opening a Previous Result File ===

As described below, expecco can generate result files in various formats and different detail. The pdf, html and junit outputs will contain summary information to be read by humans, archived or to be passed to other programs (eg. to jenkins for statistics).

The native result file (.elf) contains all trace and logging information including the original test suite.

As such, it can be archived to ensure that the test result can always be associated to the exact suite being executed, even if the suite file is lost or has been modified in the meanwhile.

These .elf result files are generated either via corresponding command line options or manually via the "''Test Results''"-"''Save Result As...''" menu item.
Like regular suite files, they can be opened via the command line or via the "''File''"-"''Open...''" menu item.

When opened, the original suite (at the time of execution), the trace- and log data and the execution times will be presented. It is even possible to re-execute individual blocks, test plans or the whole suite.

This feature is very powerful, in that it allows for the result file to be given to a developer and will help to analyse the data values, control flows and even to rerun tests and reproduce errors/failures.

=== Detailed Option Description ===

==== Information/Debugging/Logging ====

*'''<code>--help</code>''' Prints an up-to-date list of possible options and command line arguments.

*'''<code>--version</code>''' Prints the expecco release identification and exits.

*'''<code>--noBanner</code>''' (''VM option'') Suppress the splash startup banner.

*'''<code>--console</code>''' (''VM option'', ''Windows only'') Open a debug console window for Stdout and Stderr.

*'''<code>--verbose</code>''' (''VM option'') Additional startup, execution and result info is sent in human readable format to the stderr output. This is mainly meant to analyze startup problems and is actually more useful for expecco developers. It may be too much of printout, so try "''--verdicts''" instead.

*'''<code>--debug</code>''' Turns on startup debugging. By default, if an error occurs during startup, expecco terminates itself. With this option enabled, a command line debugger is opened instead. This is probably only useful for plugin developers.

*'''<code>--silent</code>''' Suppresses most info, warning and error messages which are sent to stderr/stdout. This is mainly meant to remove unwanted informational messages (for example, when plugins cannot be loaded during startup, etc.). (this option is available with expecco vsn >= 2.10)

==== Startup ====

*'''<code>--settings <fileName></code>''' Force using <fileName> instead of the default "<code>~/.expecco/.expeccoPreferences</code>" to be used for the settings file name. Useful if you want different setups to be linked to different desktop icons, or to start expecco with particular settings from a batch or shell script. To generate a preferences file, open the "''Extras''" - ''Settings''" dialog, change the settings as required, and select the "''File''"-"''Save As...''" menu item.

*'''<code>--licenseFile <fileName></code>''' Use this license, instead of the default "<code>~/.expecco/.expeccoLicense</code>". If a license server (floating licenses) is used, the license server's hostname and port information is read from the settings file.

*'''<code>--licenseServerHost <hostName></code>''' Use this host as license server, instead of the one specified in the settings file (or if no settings file was ever specified). This may be needed when running expecco as a test slave (daemon or service). (this option is available with expecco vsn >= 2.10)

*'''<code>--licenseServerPort <portNr></code>''' Use this port-nr when contacting the license server, instead of the one specified in the settings file (or if no settings file was ever specified). This may be needed when running expecco as a test slave (daemon or service). (this option is available with expecco vsn >= 2.10)

*'''<code>--noTray</code>''' (''Windows only'') Disable the tray control icon (server and execute modes only).

*'''<code>--tray</code>''' Force a tray window to be shown, even if running in non-server (slave) mode. The tray window displays the current execution status, memory situation, thread status and other internal information, which is probably only useful for developers. (this option is available with expecco vsn >= 2.10)

*'''<code>--noWindow</code>''' Do not open the main window (useful when scripting or executing only).

*'''<code>--noDisplay</code>''' Do not open any window (useful when scripting or executing only).

*'''<code>--noPlugins</code>''' Disable plugin loading. This makes startup somewhat faster, depending on the number of plugins found in your installation directory. You can still force individual plugins to be loaded using the "'''--loadPlugin'''" option. Use "''--noPlugins''" followed by a list of individual "''--loadPlugin''" options, to tune startup time with a minimum set of required plugins being loaded.

*'''<code>--loadPlugin <pluginName></code>''' Force loading a specific plugin. This is only useful if a "'''--noPlugins'''" option was given before. ''pluginName'' is the name of the folder in the "plugin" folder (under the expecco installation folder). Use "''--noPlugins''" followed by a list of individual "loadPlugin" options, to tune startup time with a minimum set of required plugins being loaded.

*'''<code>--noUpdateCheck</code>''' If configured by the user's settings, expecco automatically checks for updates and patches when started (by checking the exept web-server for the presence of new patch files). This option disables that check, even if configured in the settings. Notice, that this is usually controlled by the user settings; however, in situations where settings are shared among multiple machines (network drive) and a test host has no (or should not have) internet access, it may be useful to disable this from the command line. It is especially useful, if you are disconnected from the Internet (isolated test-lab), to avoid time delays resulting from connection failures.

*'''<code>--requireLogin</code>''' Opens expecco in a (lightweight) multi-user mode, in which a username must be entered before the actual interaction with expecco begins. This user name will be used to load custom per-user settings (named "<code>.expeccoSettings_<name></code>") and will also be used in the generated reports. Also, the "''File''" menu will contain an additional "''Logout''" menu item, which brings back the initial login dialog. This mode is useful, if expecco is used on a machine by multiple users, and expecco should remain opened (i.e. as a test stand). For example in a production floor, where tests are executed in multiple shifts by multiple operators.

*'''<code>--load <fileName or packageName></code>''' Loads a class file, extension or user plugin. The argument must be either the name of a Smalltalk source or binary file, or the name of a package (which must be found in the "<code>packages</code>" subfolder under the expecco installation folder). For details on how to generate such packages, read [[Creating_new_Class_Library_Packages/en | "Creating new Class Library Packages"]].

==== Test Execution ====
*'''<code>--execute <fileName></code>''' read and execute a suite. Starting with expecco 2.10, you can also use "-E <fileName>", which makes the command line a bit shorter.

*'''<code>--execute</code>''' without a filename, this should be the last argument of a scatter-gather dynamically generated suite command (see below: scatter-gather tests)

==== Test Selection ====

the following options allow for individual test plans to be selected for execution from a suite which contains multiple test plans. Without any such option, ''--execute'' will run all top-level testplans found in the suite in sequence.

*'''<code>--testPlanName <namePattern></code>''' Only execute test plans with a matching name. For backward compatibility, "'''<code>--testSuiteName <namePattern></code>'''" is still supported and has the same effect.

*'''<code>--testPlanTag <tagPattern></code>''' Only execute test plans with a matching tag. For backward compatibility, "'''<code>--testSuiteTag <tagPattern></code>'''" is still supported and has the same effect.

*'''<code>--testPlanID <uuid></code>''' Only execute that particular test plan (repeat to execute multiple test plans). Starting with release 2.7, the following shortcut can also be used: '''<code>--testSuiteID "<uuid1>,<uuid2>,...,<uuidN>"</code>'''. For backward compatibility, "'''<code>--testSuiteID <uuid></code>'''" is still supported and has the same effect.

==== Scatter Gather Test Suite Composition ====

these options allow for a test plan to be composed out of a single or multiple of individual suite files. When composing, a new test plan is temporarily created, which contains the specified test cases. This is in contrast to the above options, where preexisting test plans are selected for execution.

Typically, this kind of composition is used when expecco is called from a QA system, such as Polarion or HP Quality Centre, where individual "test sets" are composed out of a collection of existing test cases.

Notice, that this may lead to longer startup times, depending on the number of suites found in the suite directory, because suite files there will be opened and searched for matching test cases. If the same set of tests needs to be executed multiple times, it may be agood idea to use the "--saveSuite" option, to have the composed suite saved into a file for later reuse.

Also notice, that this works best, if testcase have unique names or are known by their ID (which is globally unique). If your test management system can provide unique identifiers, these should be used to name your testcases inside the suite (typically, a unique name of the test-case or requirement is used to name corresponding test-cases).
 (These options are only available in release ≥ 2.7)

*'''<code>--suiteDirectory <dirName></code>''' defines the directory, where test suite files are searched for composed test plans. Test cases as specified in one of the options below must be found in one of the files present there. Notice, that the first file which contains a requested test case action will be chosen. Thus, you should ensure, that only one version of each suite is present there. Typically, an up-to-date test suite directory as checked out from the revision control system is specified here. If this argument is not given, test cases are searched in the list of explicitly listed suite files (".ets" arguments).This option also specifies the directory where suites are found for remote execution (see description of SOAP and REST services below).

*'''<code>--suiteTitle <string></code>''' defines the name of the new test plan, which is created dynamically. This is used to control the labels in the generated report files.

*'''<code>--testCaseNames <name-list></code>''' defines the test cases to be included in the test by name. name-list is a list of comma-separated names of the individual test actions. Please only use this option, if your testcases have unique names and are found only once in any suite found in the suite directory. Otherwise, the first suite which contains that name will be chosen (see below for better selection options).

*'''<code>--testCaseFIDs <id-list></code>''' defines the test cases to be included in the test by function ID. id-list is a list of comma-separated UUIDs of the individual test actions. This option is probably not very user-friendly for a human, but allows for a calling program (or script) that the testcase is found even if it has been renamed in the meanwhile (remember that functional IDs are assigned once when an item is created and remain unchanged over the whole lifetime).

*'''<code>--testCaseIDs <id-list></code>''' defines the test cases to be included in the test by version ID. id-list is a list of comma-separated UUIDs of the individual test actions. This option may be very unfriendly for a human user, but allows for a calling program (or script) to ensure that a particular testcase with a particular version is found and executed, even if the testcase has been renamed or modified in the meantime (remember that the ID is changed with every modification). If the same testcase is found in multiple suite files (i.e. in different versions), this will ensure that the correct version will be executed

*'''<code>--saveSuite <fileName></code>''' saves the generated as-hoq suite. Useful if you want to archive such a dynamically generated scatter-gather suite separately from the result file(s), or to automatically construct new suites. Notice that the ".elf" result file will always include the generated ad-hoq suite, so archival of the generated ad-hoq suite is only needed if you generate pdf, html or other non-elf reports.

==== Test Parameters ====

*'''<code>--parameter <fileName></code>''' / '''<code>-P <fileName></code>''' Load a parameter set from a file. A parameter set contains values for a test suite's top environment. This can be either in XML format, as generated with the [[Environment_Editor|"''Save-Parameter-Set''" menu function]], a CSV file, containing key-value pairs or a JSON file containing a JSON dictionary object.Parameter files in either format can be created manually in a text editor, provided by a QM system (such as expeccoALM, HP Quality Center or similar), generated by another controlling program or generated by expecco itself via the "''Save-Parameter''" menu function of the [[Environment_Editor|environment editor]].The parameter file may contain values for a subset of the environment variables. In this case, the values from the parameter file overwrite corresponding values present in the loaded test suite, leaving other values unchanged.

*'''<code>--parameter:<key>=<value></code>''' / '''<code>-P:<key>=<value></code>''' Sets an individual parameter for the next "--execute" argument.If multiple "--execute" arguments are given (i.e. multiple suites are to be executed in sequence), these parameter values are collected and given to the next execution only, and overwrite corresponding values from either a parameter set (see above) or from the suite itself.Thus, it is possible to execute the same suite with different parameters in one command line (see example above). (this option is available with expecco vsn >= 2.10)

==== Test Execution via Scripting ====
*'''<code>--scriptFile <fileName></code>''' read and execute a script from a file (see scripting below).

==== Reporting ====

*'''<code>--verdicts</code>''' Send execution and result info in human readable format to the stderr output. (see [[#Verdicts Example|example below]].)

*'''<code>--logFile <fileName></code>''' Used to change the name of the generated log file, where stderr is written to. This is only useful if running in server mode.

*'''<code>--exitCode <n></code>''' Defines the exit code to be used independent of the test outcome. The default is 0 (zero) if all tests pass, and non-zero when they do not. However, some calling programs (make/jenkins,...) may misinterpret this exit code and treat the whole job as non-executable. Use this flag to prevent this. It is still possible to change the exitCode for a particular outcome by adding one of the following options after this option.

*'''<code>--exitCodeOnFail <n></code>''' Defines the exit code in case any test ends with a test-failure status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute. This option also changes the exitCodeOnError and exitCodeOnInconclusive values (see below), unless explicitly defined by those options.

*'''<code>--exitCodeOnError <n></code>''' Defines the exit code in case any test ends with a test-error status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute. This option also changes the exitCodeOnInconclusive values (see below), unless explicitly defined by that option.

*'''<code>--exitCodeOnInconclusive <n></code>''' Defines the exit code in case any test ends with an inconclusive status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute.

*'''<code>--elfReportFile <elfFilename></code>''' Writes a report in expecoo's native XML logfile format. The report contains a lot of detail information and could be processed by an XSLT processor or a similar tool. It also contains enough additional information about test plans and actions so that expecco can redisplay the activity log tree from this file. The generated file can be opened directly via the command line ("expecco <file>.elf") or by double clicking on the elf-file in the operating system's desktop.

*'''<code>--csvReportFile <csvFilename></code>''' Writes a summary report in CSV format. Each row consists of: 
** ''TESTSUITE'' - the filename
** ''TESTPLAN'' - the test plan
** ''TESTCASE'' - the test case
** ''VERDICT'' - the test result; one of SUCCESS, FAILED, ERROR or INCONCLUSIVE
** ''INFO'' - additional info in case of failure
:Additional pseudo verdicts such as STARTTIME, ENDTIME etc. are written. A typical CVS output file can be found in the [[#CSV File Example|examples]].

*'''<code>--textReportFile <textFilename></code>''' Writes a summary report in a human readable textual format. A typical text output file can be found in the [[#Textual File Example|examples]].

*'''<code>--xmlReportFile <xmlFilename></code>''' Writes a report in XML format. The report contains a lot of detail information and could usually be processed by an XSLT processor or simular tool. A typical XML output file can be found in the [[#XML File Example|examples]].

*'''<code>--pdfReportFile <pdfFilename></code>''' Writes a summary report in pdf format.

*'''<code>--htmlReportFile <htmlFilename></code>''' Writes a summary report in html format.

*'''<code>--junitReportFile <htmlFilename></code>''' Writes a summary report in a junit compatible XML format. Useful, when expecco is to be started by jenkins or similar driver programs.

*'''<code>--polarionReportFile <htmlFilename></code>''' Writes a summary report in an XML format which is especially suited for the Polarion QM tool. The structure of the generated XML is the same as with the junit format above, but a slightly different time format is used.

*'''<code>--reportTemplateName <name></code>''' Use the given report template (must be an element inside the test suite) for the following "--xxxReportFile" argument. If no such argument is given, the default template as defined in the suite is used.

==== Services ====

*'''<code>--server</code>''' Starts expecco in server mode. This combines the "''--service''", "''--infoService''" and "''--remoteControlService''" flags. All of those services as described below are started with that single command line argument.

*'''<code>--service</code>''' Starts expecco in server mode. In this mode, HTTP-SOAP and HTTP-REST requests can be used to remote-control expecco's execution; especially, to execute and monitor tests, and upload results. The most obvious use for this is for expecco to act as an execution host (test slave) for an expeccoALM or Polarion server. However, because standard protocols are used, this may also be used to interface the execution engine to many other QM management or automation systems (e.g. HP Quality Centre). The interface is described below.

*'''<code>--infoService</code>''' Provide an additional info service which allows for monitoring and control of an expecco server via a web browser (server mode only).

*'''<code>--remoteControlService</code>''' Provide an additional service to interact with a running test. Dialog requests, single stepping, starting, pausing and stopping of tests is possible via remote REST requests. This service is used by the Android remote control app, which is available upon request (server mode only).

*'''<code>--port <portNr></code>''' Used to change the HTTP and SOAP port numbers, when running in server mode. The default is 9090 (server mode only).

*'''<code>--scripting <portNr></code>''' Enable scripting (remote control via Telnet ascii interface) on portNr ([[#Scripting Example|see more below]]).

*'''<code>--allowHost <hostName></code>''' Allow hostName to connect to the scripting port. Repeat for multiple hosts (see more below).

==== Utility Functions ====

*'''<code>--diff <file1> <file2></code>''' Print differences between two test suites. This can be used eg. to automatically generate log messages for a revision control system (please read the section on "Integration with Source Code Management System" below). (This function is only available in release ≥ 2.7)

=== Command Exit Status ===

*0 - all tests passed

*>0 various other errors (command line, file not found, etc.)

*101 - at least one test failed (FAIL status). This exitCode can be overwritten by a command line argument.

*102 - at least one test was inconcusive (INCONCLUSIVE status). This exitCode can be overwritten by a command line argument.

*103 - at least one test lead to an error (ERROR status). This exitCode can be overwritten by a command line argument.
 
The diff option returns 0 if the compared suites are the same, or 200+n, (where n is the number of differences) otherwise.

== Sample Outputs ==

The following output files were generated by executing the test suite from the file:
:"C:\Programme\exept\expecco\testsuites\projects\Example.ets"
which contains a single test plan named:
:"Example Testplan"
which contains three test cases named:
:"Test1"
:"Test2"
:"Test3-Should fail"
of which the first two are supposed to PASS and the last one generates an ERROR.

All timestamp information is written in ISO8601 format.

Be reminded that the following reports are condensed reports, which only contain a subset of the information contained in expecco's native ".elf" file format. The "elf" file contains all of the execution, trace and data-flow information and the original suite as executed. "elf"-files can be reloaded at any time into the expecco UI and the test be reexecuted. Also, any of the other reports can be regenerated, posyibly with different report options (i.e. detail).

Thus it is highly recommended that these "elf" files are archived after a test run, in addition to any of the condensed report files (eg. pdf or junit report).

=== CSV File Example ("<code>--csvReportFile</code>" option) ===

By default, entries are separated by ";"-characters. Additional double quotes (") are used to delimit strings with embedded ";" or spaces. Any double quote within such a string is doubled.
CSV is a simple and very common interchange format.
For example, CSV files can be imported into Microsoft Word, Exel and Openoffice (and many other).

TESTSUITE;TESTPLAN;TESTCASE;VERDICT;INFO
;;;StartTime;2008-10-31T08:57:13.689
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test1;PASSED;
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test2;PASSED;
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";"Test3 - Should fail";ERROR;
;;;EndTime;2008-10-31T08:57:18.746

=== XML File Example ("<code>--xmlReportFile</code>" option) ===

<SummaryReport>
<StartTime>2008-10-31T08:56:49.774</StartTime>
<TestSuite>
<File>C:\Programme\exept\expecco\testsuites\projects\Example.ets</File>
<TestPlan>
<Name>Example Testplan</Name>
<TestCase>
<Name>Test 1</Name>
<Verdict>PASSED</Verdict>
</TestCase>
<TestCase>
<Name>Test 2</Name>
<Verdict>PASSED</Verdict>
</TestCase>
<TestCase>
<Name>Test 3 - Should fail</Name>
<Verdict>ERROR</Verdict>
</TestCase>
</TestPlan>
</TestSuite>
<EndTime>2008-10-31T08:56:55.142</EndTime>
</SummaryReport>

This is not to be confused with the "elf" result file format, which is also XML based, but contains a lot more detail.

Notice also, that the junit report format ("<code>--junitReport</code>" option) is similar in structure but uses different tags.
Junit reports are compatible to reports generated by Java jUnit frameworks.
They can thus be used to generate reports and trends in Jenkins/Hudson and other tools which understand the jUnit report format.

=== Textual File Example ("<code>--textReportFile</code>" option) ===

Test Execution Summary
Start: 2008-10-31 08:56:12.751
TestSuite: "C:\Programme\exept\expecco\testsuites\projects\Example.ets
TestPlan: Example Testplan
Test 1 ....................... PASSED
Test 2 ....................... PASSED
Test 3 - Should fail ......... ERROR
Finish: 2008-10-31 08:56:18.009



=== Verdicts Example ===

the "<code>--verdicts</code>" option generates a simple trace on the standard error (to be redirected into a file):

C:\selftest\commandLineArgs> expecco --noBanner --noTray --verdicts
--parameter paramesForTest.xpar --execute parameterTest.ets 
Expecco [info]: start testSuite "parameterTest.ets"...
Expecco [info]: using parameters "paramesForTest.xpar"...
Expecco [info]: start testPlan "Test Parameters From CommandLine"
Expecco [info]: start testCase "Validate Parameters"
Expecco [info]: done testCase "Validate Parameters"; STATUS=PASSED
Expecco [info]: done testPlan "Test Parameters From CommandLine"; STATUS=PASSED
Expecco [info]: done testSuite "parameterTest.ets"; STATUS=PASSED

== Integration with Quality Managament and Automation Tools ==

=== Integration with Jenkins ===

To have expecco tests being executed automatically by Jenkins, take the following example as a guideline. This is a real world setup, taken from our own setup within eXept.

# Create a test job, which is triggered by a successful build (or a change in the test suite repository)
# Check the "Block Build while prerequisite Jobs are Active" flag
# Check either the "Trigger from Source Code Management" or the "Trigger from other Job" flags
# Check "Abort build if it is Stuck" (just to make sure, that a faulty suite does not block Jenkins)
# Check "Fail the Build if Stuck" and give it a reasonable elastic Time-out Strategy (we use 300% of the last 10 builds, to make sure a longer execution time due to more test cases will not be interpreted as a stuck, and an extra timeout of 30 minutes. The timeout is very generous for the expected execution time of a few minutes).
# Check "Run xvnc during Build" to allow for monitoring, what is going on. This is also required, if the test needs a UI.
# Define the "Build Procedure" as "Execute Shell Script" (Unix/Linux) or "Execute Batch Job" (Windows)
# Enter a build procedure similar to the ours, which is:
#::<code>cd exept\expecco\application
#::del *.junit
#::expecco.com --noBanner --exitOnInternalError --noTray \
#::::--jUnitReportFile selfTestResult.junit \
#::::--execute ..\projects\expecco\eXpeccoSelfTest.ets
#::expecco.com --noBanner --noTray \
#::::--jUnitReportFile CommunicationWithExpeccoNETResult.junit \
#::::--execute ..\projects\expecco\CommunicationWithExpeccoNET.ets</code>
#:The details (especially paths and names) will of cause be different in your setup. The above uses the relative paths as it first changes the current directory to where the previous build has compiled the executable, which will of course not be the case in your setup.
# Define a "Post-build Action"
# Check "Publish Junit Test Results"
# Enter a path expression to declare the location of the resulting reports. Here, we used:<PRE>exept\expecco\application\*.junit</PRE>
# Check the "Publish Test Attachments" flag, so the results will be presented in the Jenkins management console

That's it! Because expecco has been told to generate jUnit compatible report files, we can use Jenkins' existing jUnit support. However, the jUnit xml format does not support the full range of information which is present in the native expecco result files (especially the activity log and pin value information is not included). Therefore, it is a good idea to also generate a regular ".elf" (expecco log file) and add it to the archived build artefacts.

=== Integration with expeccoALM ===
Expecco and ExpeccoALM (formerly called "''expeccoNET''") have been originally designed to work together. Therefore, only a minimum setup is required:
# ensure that an expecco test execution slave is running on each test host (server farm, virtual machines, etc.). Depending on the operating system, this is either done by installing expecco as a service (Windows), or by adding appropriate startup actions to your "init.d" files (Unix).
# define the test host(s) in expeccoALM.
# (optionally) define the devices available and attached to the execution slave machine in expeccoALM

ExpeccoALM will ask the expecco slaves about their operating system environment. So jobs will be automatically executed on matching CPU/OS machines. However, if tests require special resources (devices) to be attached, these must be defined and listed in expeccoALM as well. If your test has corresponding resource-requirements defined (see resources/inventory), expeccoALM will both ensure that the test will execute on the correct machine, and also reserve the resource during the execution. Also, test scheduling, if defined to be automatic, will be optimized to minimize resource usage, and to ensure that a higher number of tests can be executed in parallel.

=== Integration into a SOA Infrastructure ===

For this, expecco should be started on the test host(s) in so called "slave" mode.
In this mode, expecco awaits for execution commands via SOAP or REST, executes tests in the background and returns status information (progress) and results (reports).

Because tests may execute for a long time (hours or even days), the execution is performed asynchonously; first, the test has to be downloaded to the slave, then execution started. The start-command returns a ticket, which is a test-run-identifier, by which the execution progress can be queried (polled) while the test is running. Finally, a "finished" status is returned, upon which the result can be aquired via another service call.

Multiple such test slaves can be started on multiple machines, and each test slave may (if required) execute multiple tests in parallel (although this is usually limited to one, to avoid conflicts when external resources are accessed).

To start expecco in slave mode, use the command line:
expecco --service

or, if the default port (9090) is not available, use:
expecco --service --port 9090

The service interface is described below; typically, you can talk to expecco via:
http://localhost:9090/expeccoService
or:
http://localhost:9090/expeccoService/rest

The SOAP wsdl is returned via:
http://localhost:9090/wsdl/ExpeccoSOAPService.wsdl

and - if the inforService is also running - general status information with:
http://localhost:9090/info

=== Integration with HP Quality Center ===

This is described in the [[ HP Quality Center Plugin ]] document.

=== Integration with Polarion ===

This is described in the [[ Polarion Plugin]] document.

== Integration with Source Code Management Tools ==

=== Background Info on what is Contained in a ".ets" File ===

Expecco stores testsuites in a file with '.ets' extension (which stands for: "''Expecco-Test-Suite''") and result logs in '.elf' files (stands for: "''Expecco-Log-File''").
These are technically zip files - i.e. a bundle of individual files which can be extracted with the common zip command line tool (winzip under Windows systems, zip/unzip under Unix systems).

For example, "<code>unzip -l foo.ets</code>" lists the individual components, of which especially the block descriptions and attachments may be of interest.

Notice, that you have to be careful when ets-files are bundled with zip manually: for various consistency checks, expecco generates a validation signature of the components and saves this as an additional file inside the .ets file.
This signature file must be preserved and it must be consistent with the other zip-components. In effect, this means that an ets can only be constructed from the very same components, using the very same signature file as were extracted before. Otherwise, expecco refuses to load the ".ets" file later.

=== Version Management of ".ets" files ===

Unless a QA system like "expeccoALM" is used, ets-files can be stored and maintained in any other source code management (SCM) system, for example, CVS, SVN, hg/Mercurial, git, Perforce etc.
Make sure to store the .ets as binary file, and/or disable source expansion of version tag lines (for example, "$Header" or "$Id" in CVS). Consult your particular SCM system's documentation on how this is done.

As an alternative, it is possible to unzip the ets into individual components, store them separately, and zip them back into an ets, when a previous version is extracted from the SCM system. However, you must be careful to preserve the contents exactly as is, including the signature and other meta data, and not mix versions. I.e. all individual component files must be checkedIn/out in sync and as a group - it is not possible to update individual files from previous versions. The reason is that action blocks are referred to by their versionID, and these IDs will certainly be inconsistent, when previous versions of individual action blocks are mixed into another version's suite.

If, for whatever reason, you must checkin individual action blocks, we highly recommend to check in BOTH the bundled ets (and use that for later test execution), AND check in the individual components, and use only those for meta actions, such as comparison, documentation or other administrative tasks.

=== Generating Diff Lists or other Version Information ===

Many source code management systems allow for hook-scripts to be added to checkin/checkout actions, and/or to redefine the command to be used for diff-list generation.

For example, in the SVN system, an external diff tool can be defined. You could write a little shell or batch script, which calls expecco with the "<code>--diff</code>" option which is described above. Thus, you would get meaningful diff output even from checked in ets-bundle files.

The "<code>expecco --diff</code>" option is also useful as a command line tool to get diff lists - even if your SCM system does not allow for such automatic hooks.

== Scripting ==

Expecco can be scripted either by reading a script from a file or remote controlled via a telnet like command-line interface.
This is useful to execute complex test scenarios and meta tasks, to create or manipulate test suites automatically and for self-testing expecco by using another expecco to control its GUI.
It can also be used to execute and automate more complex scenarios without using expeccoALM.
 Example uses are:
* Sequentially load and/or execute all suites found in a folder, reimport libraries, save the updated suite
* Construct new suites by merging/selecting tests from other suites
* Bulk renaming, commenting, attributing etc.
* Change attachments inside a number of suites
* Controlling an application or web interface (via a GUI plugin) and saving a sequence of screen shots

By default, the scripting interface expects expressions in JavaScript syntax (but with a Smalltalk object model),
similar to the language used for elementary block definition. However, the language can be changed to Smalltalk syntax via a "~" directive.

=== Script File Example ===

To control expecco via a scriptfile, use the "<code>--scriptFile <filename></code>" command line argument, where <filename> must be a file containing JavaScript expressions.

For example, the following script file named "run3Suites.js" may contain the code:
<PRE>
// Example for an automatic expecco script.
// (loads and executes a number of test suites)
//

// to enable debugging in case of an error.
// STXScriptingServer.errorDebugging(true);

var files = [
"foo.ets",
"bar.ets",
"baz.ets",
];

Expecco::ExpeccoPreferences.current.automaticReimportOnLoad(true);
Expecco::ExpeccoPreferences.current.checkForReimportableImportsOnLoad(true);
Expecco::ExpeccoPreferences.current.checkForAnchestorOnAutomaticReimport(false);
// Expecco::ExpeccoPreferences.current.libraryPath(importPathes);

// --------------------

function executeTestPlan ( aTestPlan ) {
Stderr.nextPutLine("executing testplan "+aTestPlan.name()+"...");
resultList = aTestPlan.execute();
Stderr.nextPutLine("done.");
}

function runSuite(suiteFile) {
var loadedProject;

Stderr.nextPutLine("loading "+suiteFile+"...");
expecco.loadProjectFromFile(suiteFile);
loadedProject = expecco.project();

if (loadedProject == null) {
Stderr.nextPutLine("failed to load library "+suiteFile+".");
Smalltalk.exit(1);
} else {
loadedProject.allTestPlansDo( executTestPlan );
}
};

files.do(runSuite);
</PRE>

And can be executed with:

expecco --scriptFile run3Suites.js

for windowless operation, use the "<code>--noWindow</code>" command line argument.
To speed up the startup, you can turn off the loading of plugins, with a "<code>--noPlugins</code>" argument (and possibly load any required plugins explicitly via additional plugin arguments).
Finally, enable debug messages with a "<code>--debug</code>" argument.
Thus, the recommended options for scripting are:

expecco --debug --noPlugins --noWindow --scriptFile run3Suites.js

of course, this command line can be put into a shell (or batch) script file, and then executed with a single word command.

=== Telnet Scripting Example ===

The remote scripting service is enabled when a "<code>--scripting</code>" command line argument is given.
By default, the service only accepts connections from the local host (for security reasons). Using the "<code>--allowHost</code>" option, more hosts can be gained access to the scripting feature - but be aware, that this opens a potential security hole, as all of the internal functions can be accessed via the scripting system (and this includes the possibility to write files and call operating system services with the access rights of the one who started the scripting server).

When used with a remote script connection (telnet),
additional connection- and execution related commands are introduced by lines starting with the "~" (tilde) escape character (similar to telnet).
For example, "~." (tilde-period) is used to close the connection.
Press "~?" (tilde-question) for help.

The following is a trace of a typical scripting session (user input in bold):

c:\programs\expecco> expecco --scripting 8008
c:\programs\expecco> ... expecco now running in the background with GUI ...
...
c:\programs\expecco> telnet localhost 8008
Welcome to Expecco (Type ~? for help)
> println(expecco);
an Expecco::Browser
> expecco.menuNewProject();
...expecco performs the new-function from its menu...
> expecco.loadProjectFromFile("C:\Users\cg\testsuites\webedition\projects\BearerTest.ets");
...expecco loads the testSuite...
> expecco.close();
> ~.
Lost Connection.
c:\programs\expecco>

You can also start a scripting session without an initial expecco browser window:

c:\programs\expecco> expecco --noWindow --scripting 8008
c:\programs\expecco> ... expecco now running in the background without GUI ...
...
c:\programs\expecco> telnet localhost 8008
Welcome to Expecco (Type ~? for help)
> println(expecco);
an Expecco::Browser
> expecco;
> ~v+ // turn result-printing on
> expecco
an Expecco::Browser
> ~v- // and off again
> expecco.loadProjectFromFile("~/SomeTest.ets");
...expecco loads the testSuite...
> var blk = expecco.project.elementWithName("My Action");
> blk.name("My Fun Action");
> expecco.saveProjectToFile("~/ModifiedTest.ets");
> expecco.close();
>~.
Lost Connection.
c:\programs\expecco>

== Scripting API Overview ==

A few objects are predefined by name; among them are "''expecco''", which refers to the browser itself (i.e. the UI) and "''environment''", which refers to a collection of variable bindings (this is a dictionary of interpreter variables - not to be confused with a variable environment as known inside an expecco activity block).
 New variables can be defined with a "<code>var <name>;</code>" statement. For example:
<CODE><PRE>
var ws;

ws = new ExpeccoWorkspaceApplication;
ws.open();
ws.close();
</PRE></CODE>

==== expecco Object ====

The variable named "''expecco''" refers to the opened GUI-object, which represents the expecco application itself.

===== Expecco Functions =====

*'''project()''' the current project
*'''currentApplication()''' the current page (initially, there is only one)
*'''currentTreeApplication()''' the current tree sub-application

*'''selectModelItem( anItem )''' select an item and open an editor for it
*'''selectedModelItems()''' returns a collection of selected items
 

===== Menu Functions =====
These execute the underlying menu functions (as if clicked by the user).

*'''menuNewProject()''' creates a new testSuite
*'''menuOpen()''' opens a dialog requesting a testSuite
*'''menuExit()''' closes the expecco application

*'''loadProjectFromFile(fileNameString)''' load a testSuite
*'''saveProjectToFile(fileNameString)''' save the testSuite
*'''selectTestPlanWithName(testPlaneNameString)''' select a testplan item by name
*'''selectTestPlanWithFunctionalId(uuid)''' select a testplan item by uuid

*'''testSuite()''' retrieves the testSuite object (see below)
 

===== Test Suite (Project) Functions =====
the project as returned by the above "project()" function provides access to its elements:
 (see also [[ Expecco API#Test Suite Project Functions]])

*'''authorName()''' get the author name string
*'''authorName(aString)''' set the author name string
*'''versionString()''' get the version string
*'''versionString(aString)''' set the version string
*'''projectsWorkingDirectory()''' the directory, where attachments etc. are found
*'''ensureEnvironment()''' an instantiated environment (concrete values). See below.
*'''elementWithName( nameString )''' returns a matching element or null if not found
*'''elementWithId( aUUID )''' returns that element or null if not present. (create the UUID with "<stringConstant>.asUUID" )
*'''elementWithFunctionalId( aUUID )''' returns that element or null if not present
 

==== Environment Object ====

Environment objects are used to store key-value bindings for expecco variables. Environments form a hierarchy, where values are searched for in an environment's parent environment, if not present. This hierarchy follows the containing compound activity chain up to the project (= test suite) environment.
Additional temporary environments are kept by the executor and the browser, to keep temporary values for a single execution's or a single session's lifetime.

*'''at(key)''' retrieves a value, given the name of the entry. Raises and error if no variable exists by that name.
*'''at_ifAbsent(key, default)''' like above, but returns default if no variable exists by that name (instead of raising an error).
*'''includesKey(key)''' true if a variable by that name exists, false otherwise.
*'''at_put(key, value)''' store value as variable named key. Raises an error, in an attempt to change a readOnly variable
*'''environmentDescription()''' returns the environment's description. This describes types, default values and read/write attributes per entry.
 

==== EnvironmentDescription Object ====

This is a collection of entries which describe variables of an environment. It does only hold the description, not the bindings themself; i.e. it contains the information required to instantiate an environment. EnvironmentDescriptions inherit from OrderedCollection and therefore entries are accessed via "at:" using a numeric index from 1 to the environmentDescription's size.

Entries (as per variable) provide the following protocol:

*'''name()''' the name of the variable
*'''isReadOnly()''' true if readonly
*'''defaultValue()''' the initial value, assigned when the environment is created
*'''datatype()''' the type of the variable
*'''comment()''' description
 

== Remote Controlling and Monitoring Expecco ==

Expecco itself can be automated by various mechanisms:

* via command line arguments (described in [[ #Command Line | "Command Line"]] above)

* via script files (see [[ #Script File Example | "Script File Example"]] above)

* via the telnet interface (see [[ #Telnet Scripting Example | "Telnet Scripting Example"]] above)

* via standard RPC mechanisms, such as SOAP or REST.

Especially the RPC mechanisms are useful to integrate expecco into the company test infrastructure.
Such interfaces are meant for programmatic control of an expecco slave from quality management, application life cycle and other scheduling tools.
Our own companion product, ExpeccoALM and third party tools, such as Polarion use these service interfaces.

Notice, that for integration into a Jenkins infrastructure, command line arguments or scripts may be a more cost efective means to control automated expecco testruns.

=== Expecco as a Slave Node in a Test Lab ===

The service interfaces are useful to control unmonitored slave machines in the network, among which expecco test execution jobs are scheduled by another program. ExpeccoALM and other quality management tools use these to initiate test runs in a test server farm.
For this, the basic operations "download of a suite", "execute a suite" and "requesting execution results" are available as service calls.

Both SOAP and REST services are available, if expecco is started with the "''--server''" argument.
An optional "''--port''" argument allows for the HTTP port to be changed from the default (9090) on which expecco is listening.

For debugging and testing, the service can be also be started from the interactive UI, via expecco's main menu (in the "''Extras''" - "''Web-Services''" - "''Start / Stop''" menu items).

These services use HTTP requests as transport layer.

==== Expecco SOAP Service Interface ====

This accepts SOAP requests, via the URL "<code>/expeccoService</code>". I.e. the default URL is "<code>host:9090/expeccoService</code>".
A partial WSDL spec can be aqcuired from the running service via "<code>host:9090/wsdl/ExpeccoSOAPService.wsdl</code>" (partial, because it is currently not does not contain complete type information).

The service entries are:

===== Loading and Executing a Suite =====

The execute request is the main service entry. It passes the suite and also optional parameters.

The test suite can be bade available to expecco either by passing it with the request (as base64 CDATA), or by passing a URL from which expecco can fetch the suite iteslf.

The execute call contains the following fields:

<message name="expecco_executeProject_v5_Request">
<part name="id" type="UUID"/>
<part name="testSuiteId" type="UUID"/>
<part name="dataSource" type="xsd:string"/>
<part name="dataSourceUri" type="xsd:string"/>
<part name="environment" type="xsd:arrayType"/>
<part name="testplans" type="xsd:arrayType"/>
<part name="resources" type="xsd:arrayType"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

and responds with:

<message name="expecco_executeProject_v5_Response">
<part name="result" type="xsd:string"/>
</message>

This call starts execution, and immediately returns a response, which consists of an identifier.
This identifier can later be used to ask expecco about the execution status. As a test may take a long time to finish,
it is useful to poll via status requests from time to time, to see if the execution has finished and to get progress status.

The parameters are:

* id - mandatory; a ticket ID; this should be a UUID-string, to avoid possible conflicts
* testSuiteId - mandatory; the UUID of the suite to execute. See below for details about download optimizations
* dataSource - optional; if present, this should contain the whole ets-file's contents as a Base64 encoded CDATA string
* dataSourceUri - optional; if present, this should be the URI from which expecco shall fetch the suite. See below for details
* environment - optional; top-level environment variable values. This can be used to provide alternative initial values for variables in the top level variable environment (the "Project-Environment")
* testplans - optional; a list of UUIDs of testplans to execute. If not present, all top-level testplans are executed
* resources - optional; a list of resources to be used by the test (see expeccoALM resource description)
* optionalParameters - optional; an array containing additional parameters as key-value elements.

The "optionalParameters" field:

A list of key-value elements (i.e. must have an even number of elements, of the form [k1 v1 k2 v2 ... kN vN] ).
Each key is an xsd:string, each value's type depends on the key, but all of them are currently also strings.
The list of supported parameters is open for future extension of the interface. Currently, the following are recognized:
* [ "generateLog" xsd:boolean ] - the boolean arg must be "true" or "false"
* [ "generatePDFReport" xsd:boolean ] - boolean arg, must be either "true" or "false"

The "testplans" field:

this allows selective execution of individual test plans and also individual test cases (from within a test plan) from the suite.
If not present, all test plans as present in the suite are executed.
If present, the testPlans parameter must be an xsdarray of pairs (i.e. each array element is again an xsdarray with 2 elements).
Each top level element describes one testplan to be executed. The first element of each being the testplan's UUID, the second another array, listing the testcases by UUID.
For example, if the suite contains three testplans, named "a", "b" and "c", with plan "a" having id-a and "b" having id-b as UUID.
A testPlans argument might look like:
<pre>
[
[ id-a ]
[ id-b [ id-tcb-1 id-tcb-2 ] ]
]
</pre>
and specify that testplan "a" should be executed fully (i.e. all test cases), and only the testcases tcb-1 and tcb-2 are to be executed from testplan "b".

The "environment" field:

-- to be described --

The "resources" field:

-- to be described --

The reply consists of the ticket-id, which has to be passed in further status requests.

===== Loading Only =====

It is also possible, to download a suite without execution, via the "download" request:

<message name="expecco_downloadProject_Request">
<part name="testSuiteId" type="xsd:string"/>
<part name="dataSourceBase64" type="xsd:string"/>
<part name="dataSourceUri" type="xsd:string"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

<message name="expecco_downloadProject_Response">
<part name="result" type="xsd:string"/>
</message>

===== Download Optimization =====

Expecco remembers downloaded suites in a temporary folder, to avoid repeated transfers of possibly huge test suites.
If a URI is passed (but no base64 encoded data), expecco checks if the suite is already present on the test host,
and will not fetch it again, if already present. If not present, expecco will fetch the suite via a HTTP request from the URI.

If no URI is passed (i.e. both data and dataURI fields are empty), expecco will either respond with an error reply, if not present,
or with an ok response, if already present.

Thus, if you have to pass the suite as data (i.e. there is no file service available, from which expecco could fetch the suite),
it is recommended to first check if a suite is already present (by sending a download request without data) and check for an error return. If no error is reported, the suite is already there and no further download action is required. If there is an error response,
the client should send the suite with another download request, this time with a non-empty data field.

After any successfull download (either via download, or via execute request), the suite can be executed by an execute request without data.

===== Execution by Suite File Name =====

An alternative to downloading suites is to execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.
The executeTestSuiteFile-request is used to execute one of the suites in that directory.

The call contains the following fields:

<message name="expecco_executeTestSuiteFile_Request">
<part name="id" type="UUID"/>
<part name="fileName" type="xsd:string"/>
<part name="environment" type="xsd:arrayType"/>
<part name="testplans" type="xsd:arrayType"/>
<part name="resources" type="xsd:arrayType"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

If successful, a ticketID is returned (same as above execute-request).

===== Status Request =====

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the above execute request.

<message name="expecco_getExecutionInfo_Request">
<part name="ticketId" type="UUID"/>
</message>

<message name="expecco_getExecutionInfo_Response">
<part name="result" type="xsd:string"/>
</message>

A client may have to send multiple "getExecutionInfo" requests, until a "finished" status is returned.
Expecco will keep the generated reports and log files in a temporary folder, until fetched via a getResult request.
This allows for both expecco and the client to be turned off and restarted, without loosing any status information.

===== Result Request =====

Once finished, reports and log files should be fetched from expecco.

<message name="expecco_getResult_Request">
<part name="ticketId" type="UUID"/>
<part name="removeResultBoolean" type="xsd:string"/>
</message>

<message name="expecco_getResult_Response">
<part name="result" type="xsd:string"/>
</message>

After the "getResult" request, corrsponding files are automatically removed from the temporary folder by expecco.

===== Terminate/Abort Request =====

Use this, to abort and terminate an ongoing test execution.

<message name="expecco_killExecution_Request">
<part name="ticketId" type="xsd:string"/>
</message>

<message name="expecco_killExecution_Response">
<part name="result" type="xsd:string"/>
</message>

===== Remove Ticket Request =====

Use this, to tell expecco, that no further interest exists in a ticket.
If the test is still running, it is aborted. If it is about to be started, it will not be.
Any temporary files which might have already been created due to this execution are removed.

<message name="expecco_killExecution_Request">
<part name="ticketId" type="UUID"/>
</message>

<message name="expecco_killExecution_Response">
<part name="result" type="xsd:string"/>
</message>

===== Ping =====

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

<message name="ping_Request">
</message>

<message name="ping_Response">
<part name="result" type="xsd:array"/>
</message>

===== Cleanup of Old Result/Log Files =====

This request can be used to remove all temporary files, especially leftover report- and log files.
This should be used, if a client has crashed, and lost track of

<message name="expecco_cleanupTempFiles_Request">
</message>

<message name="expecco_cleanupTempFiles_Response">
<part name="result" type="xsd:string"/>
</message>

===== Example Wire Protocol Trace =====

Client asks expecco to execute a suite.

<-- HTTP Request to Expecco --
<PRE>

POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 8925
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">

<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_executeProject_v5 xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<optionalParameters xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[6]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">generateReport</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">generateLog</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">runAllTestcasesIfEmptyTestcaseList</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
</optionalParameters>

<testSuiteId xsi:type="UUID">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<testplans
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:arrayType[1]">
<item
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
enc:arrayType="xsd:anyType[2]">
<item
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xsi:type="xsd:string">f71c4700-7477-11df-a41b-00ff7b08316c
</item>
<item
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
enc:arrayType="xsd:anyType[0]">
</item>
</item>
</testplans>
<id xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</id>
<dataSource xsi:null="1"/>
<dataSourceUri xsi:type="xsd:string">http://127.0.0.1:8662/expeccoALM/tentativeObjects/a84b2d96-d133-47db-9fc2-17208b490bfe.a
</dataSourceUri>
<environment
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[22]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Host__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">sr-laptop</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_LoginUserName__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">admin</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_FullUserName__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">. *admin*</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_TestHost__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">127.0.0.1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_UUID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">e5c9cb30-a253-11e4-9f24-c48508c91d3c</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_ID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">d4</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_Name__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Test For Resources and Skills</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_Summary__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string"></item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Run_UUID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">200d93e1-a258-11e4-b9eb-c48508c91d3c</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Run_ID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">r14</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_TestSuite_VersionNumber__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">1</item>
</environment>

<resources
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[28]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute1-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute2-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute2-2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Float</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0.0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 2 eeee</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute1-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
</resources>
</m:expecco_executeProject_v5>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco

<PRE>

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 649
Connection: Keep-Alive

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_executeProject_v5Response xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</result>
</m:expecco_executeProject_v5Response>
</env:Body>
</env:Envelope>

</PRE>

Client asks expecco for execution state

<-- HTTP Request to expecco

<PRE>

POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 635
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfo xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<ticketId xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</ticketId>
</m:expecco_getExecutionInfo>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco (while still executing)

<PRE>

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 2579
Connection: Keep-Alive

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfoResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result>
<executionResultState xsi:type="xsd:string">executingTestSuite</executionResultState>
<currentActivity xsi:type="xsd:string">executing Neuer Testplan</currentActivity>
<pdfReportFileURL xsi:null="1"/>
<summaryResult>
<summaryTestplanExecutionResults xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<summaryTestPlanItems xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<detailString xsi:null="1"/>
<resultActivityState xsi:type="xsd:string">Successful</resultActivityState>
<testplanItemName xsi:type="xsd:string">Neue Aktion</testplanItemName>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanItemExecutionResult</expeccoClass>
</item>
</summaryTestPlanItems>
<testPlanId xsi:type="xsd:string">22623ef0-757d-11df-a41b-00ff7b08316c</testPlanId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanExecutionResult</expeccoClass>
<testPlanName xsi:null="1"/>
</item>
</summaryTestplanExecutionResults>
<testSuiteName xsi:type="xsd:string">Test For Resources and Skills</testSuiteName>
<testSuiteId xsi:type="xsd:string">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestSuiteExecutionResult</expeccoClass>
</summaryResult>
<logFileURL xsi:null="1"/>
<expeccoClass xsi:type="xsd:string">Expecco::SoapExecutionResult::SummaryEncoding</expeccoClass>
<executionProgress xsi:type="xsd:integer">0</executionProgress>
</result>
</m:expecco_getExecutionInfoResponse>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco (after execution)

<PRE>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 2781
Connection: Keep-Alive

.....................
<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfoResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result>
<executionResultState xsi:type="xsd:string">finished</executionResultState>
<currentActivity xsi:type="xsd:string">executing Neuer Testplan</currentActivity>
<pdfReportFileURL xsi:type="xsd:string">http://127.0.0.1:9090/expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.pdf</pdfReportFileURL>
<summaryResult>
<summaryTestplanExecutionResults xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<summaryTestPlanItems xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<detailString xsi:null="1"/>
<resultActivityState xsi:type="xsd:string">Successful</resultActivityState>
<testplanItemName xsi:type="xsd:string">Neue Aktion</testplanItemName>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanItemExecutionResult</expeccoClass>
</item>
</summaryTestPlanItems>
<testPlanId xsi:type="xsd:string">22623ef0-757d-11df-a41b-00ff7b08316c</testPlanId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanExecutionResult</expeccoClass>
<testPlanName xsi:null="1"/>
</item>
</summaryTestplanExecutionResults>
<testSuiteName xsi:type="xsd:string">Test For Resources and Skills</testSuiteName>
<testSuiteId xsi:type="xsd:string">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestSuiteExecutionResult</expeccoClass>
</summaryResult>
<logFileURL xsi:type="xsd:string">http://127.0.0.1:9090/expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.elf</logFileURL>
<expeccoClass xsi:type="xsd:string">Expecco::SoapExecutionResult::SummaryEncoding</expeccoClass>
<executionProgress xsi:type="xsd:integer">100</executionProgress>
</result>
</m:expecco_getExecutionInfoResponse>
</env:Body>
</env:Envelope>

</PRE>

Client fetches the report and log files from expecco:

<-- HTTP Request to expecco (fetch logfile)

<PRE>
GET /expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.elf HTTP/1.1
Connection: Keep-Alive
User-Agent: Mozilla/3.0N
Host: 127.0.0.1:9090
Accept-Encoding: chunked
Accept-Language: en,*
Accept-Charset: iso-8859-1,*,utf-8
Accept: */*
</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: application/x-expecco-logfile
Content-Length: 12690
Connection: Keep-Alive
Cache-Control: max-age=86400
Last-modified: Thu, 22 Jan 2015 17:32:50 GMT

... a lot of elf-file data ...
</PRE>

<-- HTTP Request to expecco (fetch pdf report)

<PRE>
GET /expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.pdf HTTP/1.1
Connection: Keep-Alive
User-Agent: Mozilla/3.0N
Host: 127.0.0.1:9090
Accept-Encoding: chunked
Accept-Language: en,*
Accept-Charset: iso-8859-1,*,utf-8
Accept: */*
</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 29768
Connection: Keep-Alive
Cache-Control: max-age=86400
Last-modified: Thu, 22 Jan 2015 17:32:51 GMT

... a lot of pdf data ...
</PRE>

Client releases ticket (so expecco can remove the temporary data)

<-- HTTP Request to expecco

<PRE>
POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 627
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_removeTicket xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<ticketId xsi:type="UUID">ad8011e1-a25c-11e4-b9eb-c48508c91d3c</ticketId>
</m:expecco_removeTicket>
</env:Body>
</env:Envelope>

</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 614
Connection: Keep-Alive

.....................
<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_removeTicketResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result xsi:type="xsd:boolean">true</result>
</m:expecco_removeTicketResponse>
</env:Body>
</env:Envelope>

</PRE>
===== Example Session Using "<code>wget</code>" =====

Using "wget" with SOAP is possible, but a little complicated, because correct SOAP requests have to be constructed, and ticket-numbers be extracted from responses. It is much easier with the REST service.

See below for a description.

==== Expecco REST Service Interface ====

This accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

The REST service supports the same set of operations as the SOAP service described above, but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are all HTTP-GET requests, possibly with attached JSON encoded argument data.
The operation is determined by the URI: the last component is the operation name to be executed.

See details [[ Starting_expecco_via_Command_Line/rest | "expecco rest service interface"]].

===== ProtocolInfo Request "/expeccoService/rest/protocolInfo" =====

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE"; currently always "GET"
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

{
"URLPath" : "expeccoService/rest" ,
"Service" : "ExpeccoRestService",
"Version" : 1 ,
"Protocol" :
[
{
"Name" : "execute" ,
"Request" : "GET" ,
"Argument" : "(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "start execution; return ticketID." ,
},
{
"Name" : "download" ,
"Request" : "GET" ,
"Argument" : "(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "start execution; return ticketID." ,
},
{
"Name" : "executeTestSuiteFile" ,
"Request" : "GET" ,
"Argument" : "(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "execute suite file; return ticketID." ,
},
{
"Name" : "getExecutionInfo" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Return" : "Dictionary"
"Comment" : "get execution status of an execute job; argument is ticketID." ,
},
{
"Name" : "killExecution" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Comment" : "kill execution of an execute job; argument is ticketID."
},
{
"Name" : "removeTicket" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Comment" : "give up execution of an execute job; if required, kill the job. argument is ticketID."
},
{
"Name" : "cleanupTempFiles" ,
"Request" : "GET" ,
"Comment" : "remove leftover temporary files."
},
{
"Name" : "ping" ,
"Request" : "GET" ,
"Comment" : "test reachability and return some status info." ,
"Return" : "Dictionary"
},
{
"Name" : "protocolInfo" ,
"Request" : "GET",
"Return" : "Dictionary"
}

]
}

===== Execute Request "/expeccoService/rest/execute" =====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

===== Download Request "/expeccoService/rest/download" =====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.

===== Execute File Request "/expeccoService/rest/executeTestSuiteFile" =====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

The file must be present/reachable by the expecco slave.
It may be either an absolute pathname (typically on a shared network drive) or
a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

===== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" =====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

===== KillExecution Request "/expeccoService/rest/killExecution" =====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

===== RemoveTicket Request "/expeccoService/rest/removeTicket" =====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

===== Cleanup Request "/expeccoService/rest/cleanupTempFiles" =====

No argument. no return value.

===== Ping Request "/expeccoService/rest/ping" =====

No argument. Returns an object containing status information.

 

===== Example Wire Protocol Trace =====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>

===== Example Session Using "<code>wget</code>" =====

Using "wget" with SOAP is possible, but a little complicated, because correct SOAP requests have to be constructed, and ticket-numbers be extracted from responses. It is much easier with the REST service.

Assuming, you have a folder containing 3 suites "suiteA.ets", "suiteB.ets" and "suiteC.ets", and you want to send them to a running expecco slave via REST, here is how to do it:

1) to check if the expecco slave is up and running, send it a

=== Expecco Remote Control REST Service Interface ===

A secondary REST service is available to interact with a running test.
This service is used by the "expecco remote control App", which is available for Android devices (tablets and cell phones).

This accepts REST requests, via the URL "/remote". I.e. the default URL is "host:9090/remote".
A description of the supported REST calls can be aqcuired from the running service via "host:9090/remote/protocolInfo".

When this service is active, the standard Dialog requests (input boxes, with "OK"/"Cancel" buttons) will also be presented on the remote controlling app, and can be answered either on the PC-screen OR on a remote android device.
An obvious application of this is when the test system (hardware) needs manual interaction and you have to leave the workplace for this. Here, it is very convenient to be able to answer questions like "Insert Cable X and press OK to proceed" from a mobile device. Avoiding the need to walk back to the workplace to click on the "OK" button.

=== Expecco Short Status Information Service ===

This is a very simple HTTP service, which delivers a single page with a status overview.
This service is started when the "<code>--infoService</code>" or "<code>--server</code>" command line arguments are present.

This accepts HTTP requests, via the URL "/info".
I.e. the default URL is "<code>host:9090/info</code>".

The main use of this service is to quickly check the status of a testslave from a remote webbrowser,
without a need for a more complicated SOAP or REST service client.

Back to [[Online_Documentation#Topic:_Execution | Online Documentation]]

Starting expecco via Command Line/en

2017-04-02T12:48:18Z

Ab:

== Introduction ==

expecco can be started manually via the command line, by batch or shell scripts or automatically via the crontab (Unix) or scheduled tasks / services (Windows) mechanism of the operating system. Thus, you can have tests to execute unattended and without GUI "overnight". This is also the method to integrate expecco with other quality tools, such as Jenkins, HP-Quality Center, Polarion, expeccoALM etc.

Command line options allow for test suites to be loaded, executed and result files being generated without requiring user interaction.

In addition to the above, expecco can also be started in a slave mode as a service, to wait for incoming test-run request from a QM system, such as expeccoALM or Polarion. Expecco can respond to request via SOAP or REST calls to load, execute and report test suites. The expeccoNET automation environment assumes that expecco is already running on each slave host, and each has been started with a "--server" command line argument. It uses HTTP+SOAP/REST to communicate with those expecco slaves by default.

In this later "slave mode", expecco is installed to run as a daemon process (under Unix) or as a service (under Windows), and will be automatically started by the operating system, when it boots. The details of how it is installed vary between operating systems: under Unix, it needs to be registered in the init-tab-folder, under Windows it needs to be installed as a Windows service.

== Command Line ==

If expecco is started without command line arguments, it will open up showing the initial welcome screen. The same behavior as if started via the desktop.

With a single file argument, expecco will read a test suite from the given file and open an editor window on it (but will not execute it).

'''expecco <testsuite filename>'''

This is the same behavior as if a test suite file (.ets) is dropped onto the expecco icon via the desktop.

The simplest command line to execute a test suite is:

'''expecco --execute <testsuite filename> ...'''

:<testsuite filename> is the test suite's filename, as saved from within the expecco GUI application. This should be a saved ".ets" testSuite file. If more than one test suite filename is given, each is processed in sequence. All top-level test plans as found in the test suite(s) are executed (see below for more options).

:By default, the overall execution outcome is returned by the command's return value (exit code), which is
::0 - all PASSED
::non-zero - any ERROR, FAILURES or INCONCLUSIVE items.

The return value is useful if expecco is started via a makefile, or from jenkins for example. If the caller needs a different exit code, use one of the exitCodeOnXXX options as described below. This is useful to avoid a ''make'' or ''jenkins'' process from stopping.

To get a list of available options, type:
'''expecco --help'''

=== Command Line Options ===
Command line options are handled at two places: the runtime system (Smalltalk/X VM) and the expecco application itself.
When expecco is started, the VM is first to look for command line arguments and processes any of the VM options, until
a non-VM option is encountered. It passes the remaining options to expecco's main entry.
Thus, any option which is given after the first non-VM option will not be handled by the VM, but by expecco. Therefore, no VM options should be placed after the first non-VM option. VM options are marked as "''VM option''" in the list below.

Also, some options are specific to the operating system, on which expecco is executed. These are marked as "''Windows''", "''Linux''" etc.

=== Recommended Command Line Options ===

To start expecco on an existing test suite, use:

'''expecco <testsuite filename>'''

this is also the way expecco is started, when a test suite file is double-clicked on the Linux or Windows desktop, or when a test-suite document is dropped onto the expecco icon.
The above opens the expecco GUI and loads the given test suite initially. However, it does not automatically execute any test.

To execute a suite, add a "'''--execute'''" argument (or in expecco 2.10, "-E"), as in:

'''expecco --execute <testsuite filename>'''

You will notice, that expecco shows a banner intitially; this can be disabled with a '''--noBanner''' option. Also, under windows, a small tray icon is shown in the lower right, which provides a controlling UI. This is disabled with '''--noTray'''.

Finally, as mentioned before, the test's outcome is reported via the exit code. If you want a little more information on the status of individiual test cases, use a '''--verdicts''' option.

This makes the following a good start for your command line:

'''expecco --noBanner --noTray --verdicts --execute <testsuite filename>'''

or, if you want to use a special parameter-file, to provide values for (some of) the project-variables:

'''expecco --noBanner --noTray --verdicts --parameter <param-file> --execute <filename>'''

Parameter files are XML, CSV or JSON-files containing key-value pairs. They are usually created by saving an environment from within the expecco GUI (see [[Environment Editor]]).

All of the above command lines opened an expecco UI window.
To execute a suite without GUI, add a "'''--noWindow'''" argument.

To compose "scatter-gather" test cases from possibly multiple suites, found in a directory use:

'''expecco --suiteDirectory <dirName> --testCaseNames "T01,T02,T05" --execute'''

or, to explicitly specify the suite-files where test cases are taken from, use:

'''expecco --testCaseNames "T01,T02,T05" --execute <suiteFile1>.ets <suiteFile2>.ets ...'''

Finally, to get a report, add a "'''--xxxReportFile <fileName>'''" argument, as in:

'''expecco --noBanner --noWindow --noTray --verdicts --parameter <param-file>''' \
''' --pdfReportFile result.pdf --execute <filename>'''

All options are described in more detail below.

=== Executing Multiple Test Suites in Sequence ===

It is possible to run multiple (possibly different) test suites with one command line to reduce startup and project loading times.
For this, provide multiple "--execute <filename>" arguments to the command line, as in:

'''expecco --execute <suiteFile1>.ets --execute <suiteFile2>.ets ...'''

with this command line, expecco first executes the toplevel testplan(s) from "suiteFile1.ets", then those from "suiteFile2.ets". All parameters (i.e. top-level variable values) will be taken from within the corresponing suite file.

To change individual parameters, use "--parameter:key=value" arguments before the corresponing --execute argument. For example, to execute the same suite with different parameters, use a command line like:

'''expecco --parameter:device=samsung --execute mobileTest.ets''' \
''' --parameter:device=nexus --execute mobileTest.ets'''

=== Opening a Previous Result File ===

As described below, expecco can generate result files in various formats and different detail. The pdf, html and junit outputs will contain summary information to be read by humans, archived or to be passed to other programs (eg. to jenkins for statistics).

The native result file (.elf) contains all trace and logging information including the original test suite.

As such, it can be archived to ensure that the test result can always be associated to the exact suite being executed, even if the suite file is lost or has been modified in the meanwhile.

These .elf result files are generated either via corresponding command line options or manually via the "''Test Results''"-"''Save Result As...''" menu item.
Like regular suite files, they can be opened via the command line or via the "''File''"-"''Open...''" menu item.

When opened, the original suite (at the time of execution), the trace- and log data and the execution times will be presented. It is even possible to re-execute individual blocks, test plans or the whole suite.

This feature is very powerful, in that it allows for the result file to be given to a developer and will help to analyse the data values, control flows and even to rerun tests and reproduce errors/failures.

=== Detailed Option Description ===

==== Information/Debugging/Logging ====

*'''<code>--help</code>''' Prints an up-to-date list of possible options and command line arguments.

*'''<code>--version</code>''' Prints the expecco release identification and exits.

*'''<code>--noBanner</code>''' (''VM option'') Suppress the splash startup banner.

*'''<code>--console</code>''' (''VM option'', ''Windows only'') Open a debug console window for Stdout and Stderr.

*'''<code>--verbose</code>''' (''VM option'') Additional startup, execution and result info is sent in human readable format to the stderr output. This is mainly meant to analyze startup problems and is actually more useful for expecco developers. It may be too much of printout, so try "''--verdicts''" instead.

*'''<code>--debug</code>''' Turns on startup debugging. By default, if an error occurs during startup, expecco terminates itself. With this option enabled, a command line debugger is opened instead. This is probably only useful for plugin developers.

*'''<code>--silent</code>''' Suppresses most info, warning and error messages which are sent to stderr/stdout. This is mainly meant to remove unwanted informational messages (for example, when plugins cannot be loaded during startup, etc.). (this option is available with expecco vsn >= 2.10)

==== Startup ====

*'''<code>--settings <fileName></code>''' Force using <fileName> instead of the default "<code>~/.expecco/.expeccoPreferences</code>" to be used for the settings file name. Useful if you want different setups to be linked to different desktop icons, or to start expecco with particular settings from a batch or shell script. To generate a preferences file, open the "''Extras''" - ''Settings''" dialog, change the settings as required, and select the "''File''"-"''Save As...''" menu item.

*'''<code>--licenseFile <fileName></code>''' Use this license, instead of the default "<code>~/.expecco/.expeccoLicense</code>". If a license server (floating licenses) is used, the license server's hostname and port information is read from the settings file.

*'''<code>--licenseServerHost <hostName></code>''' Use this host as license server, instead of the one specified in the settings file (or if no settings file was ever specified). This may be needed when running expecco as a test slave (daemon or service). (this option is available with expecco vsn >= 2.10)

*'''<code>--licenseServerPort <portNr></code>''' Use this port-nr when contacting the license server, instead of the one specified in the settings file (or if no settings file was ever specified). This may be needed when running expecco as a test slave (daemon or service). (this option is available with expecco vsn >= 2.10)

*'''<code>--noTray</code>''' (''Windows only'') Disable the tray control icon (server and execute modes only).

*'''<code>--tray</code>''' Force a tray window to be shown, even if running in non-server (slave) mode. The tray window displays the current execution status, memory situation, thread status and other internal information, which is probably only useful for developers. (this option is available with expecco vsn >= 2.10)

*'''<code>--noWindow</code>''' Do not open the main window (useful when scripting or executing only).

*'''<code>--noDisplay</code>''' Do not open any window (useful when scripting or executing only).

*'''<code>--noPlugins</code>''' Disable plugin loading. This makes startup somewhat faster, depending on the number of plugins found in your installation directory. You can still force individual plugins to be loaded using the "'''--loadPlugin'''" option. Use "''--noPlugins''" followed by a list of individual "''--loadPlugin''" options, to tune startup time with a minimum set of required plugins being loaded.

*'''<code>--loadPlugin <pluginName></code>''' Force loading a specific plugin. This is only useful if a "'''--noPlugins'''" option was given before. ''pluginName'' is the name of the folder in the "plugin" folder (under the expecco installation folder). Use "''--noPlugins''" followed by a list of individual "loadPlugin" options, to tune startup time with a minimum set of required plugins being loaded.

*'''<code>--noUpdateCheck</code>''' If configured by the user's settings, expecco automatically checks for updates and patches when started (by checking the exept web-server for the presence of new patch files). This option disables that check, even if configured in the settings. Notice, that this is usually controlled by the user settings; however, in situations where settings are shared among multiple machines (network drive) and a test host has no (or should not have) internet access, it may be useful to disable this from the command line. It is especially useful, if you are disconnected from the Internet (isolated test-lab), to avoid time delays resulting from connection failures.

*'''<code>--requireLogin</code>''' Opens expecco in a (lightweight) multi-user mode, in which a username must be entered before the actual interaction with expecco begins. This user name will be used to load custom per-user settings (named "<code>.expeccoSettings_<name></code>") and will also be used in the generated reports. Also, the "''File''" menu will contain an additional "''Logout''" menu item, which brings back the initial login dialog. This mode is useful, if expecco is used on a machine by multiple users, and expecco should remain opened (i.e. as a test stand). For example in a production floor, where tests are executed in multiple shifts by multiple operators.

*'''<code>--load <fileName or packageName></code>''' Loads a class file, extension or user plugin. The argument must be either the name of a Smalltalk source or binary file, or the name of a package (which must be found in the "<code>packages</code>" subfolder under the expecco installation folder). For details on how to generate such packages, read [[Creating_new_Class_Library_Packages/en | "Creating new Class Library Packages"]].

==== Test Execution ====
*'''<code>--execute <fileName></code>''' read and execute a suite. Starting with expecco 2.10, you can also use "-E <fileName>", which makes the command line a bit shorter.

*'''<code>--execute</code>''' without a filename, this should be the last argument of a scatter-gather dynamically generated suite command (see below: scatter-gather tests)

==== Test Selection ====

the following options allow for individual test plans to be selected for execution from a suite which contains multiple test plans. Without any such option, ''--execute'' will run all top-level testplans found in the suite in sequence.

*'''<code>--testPlanName <namePattern></code>''' Only execute test plans with a matching name. For backward compatibility, "'''<code>--testSuiteName <namePattern></code>'''" is still supported and has the same effect.

*'''<code>--testPlanTag <tagPattern></code>''' Only execute test plans with a matching tag. For backward compatibility, "'''<code>--testSuiteTag <tagPattern></code>'''" is still supported and has the same effect.

*'''<code>--testPlanID <uuid></code>''' Only execute that particular test plan (repeat to execute multiple test plans). Starting with release 2.7, the following shortcut can also be used: '''<code>--testSuiteID "<uuid1>,<uuid2>,...,<uuidN>"</code>'''. For backward compatibility, "'''<code>--testSuiteID <uuid></code>'''" is still supported and has the same effect.

==== Scatter Gather Test Suite Composition ====

these options allow for a test plan to be composed out of a single or multiple of individual suite files. When composing, a new test plan is temporarily created, which contains the specified test cases. This is in contrast to the above options, where preexisting test plans are selected for execution.

Typically, this kind of composition is used when expecco is called from a QA system, such as Polarion or HP Quality Centre, where individual "test sets" are composed out of a collection of existing test cases.

Notice, that this may lead to longer startup times, depending on the number of suites found in the suite directory, because suite files there will be opened and searched for matching test cases. If the same set of tests needs to be executed multiple times, it may be agood idea to use the "--saveSuite" option, to have the composed suite saved into a file for later reuse.

Also notice, that this works best, if testcase have unique names or are known by their ID (which is globally unique). If your test management system can provide unique identifiers, these should be used to name your testcases inside the suite (typically, a unique name of the test-case or requirement is used to name corresponding test-cases).
 (These options are only available in release ≥ 2.7)

*'''<code>--suiteDirectory <dirName></code>''' defines the directory, where test suite files are searched for composed test plans. Test cases as specified in one of the options below must be found in one of the files present there. Notice, that the first file which contains a requested test case action will be chosen. Thus, you should ensure, that only one version of each suite is present there. Typically, an up-to-date test suite directory as checked out from the revision control system is specified here. If this argument is not given, test cases are searched in the list of explicitly listed suite files (".ets" arguments).This option also specifies the directory where suites are found for remote execution (see description of SOAP and REST services below).

*'''<code>--suiteTitle <string></code>''' defines the name of the new test plan, which is created dynamically. This is used to control the labels in the generated report files.

*'''<code>--testCaseNames <name-list></code>''' defines the test cases to be included in the test by name. name-list is a list of comma-separated names of the individual test actions. Please only use this option, if your testcases have unique names and are found only once in any suite found in the suite directory. Otherwise, the first suite which contains that name will be chosen (see below for better selection options).

*'''<code>--testCaseFIDs <id-list></code>''' defines the test cases to be included in the test by function ID. id-list is a list of comma-separated UUIDs of the individual test actions. This option is probably not very user-friendly for a human, but allows for a calling program (or script) that the testcase is found even if it has been renamed in the meanwhile (remember that functional IDs are assigned once when an item is created and remain unchanged over the whole lifetime).

*'''<code>--testCaseIDs <id-list></code>''' defines the test cases to be included in the test by version ID. id-list is a list of comma-separated UUIDs of the individual test actions. This option may be very unfriendly for a human user, but allows for a calling program (or script) to ensure that a particular testcase with a particular version is found and executed, even if the testcase has been renamed or modified in the meantime (remember that the ID is changed with every modification). If the same testcase is found in multiple suite files (i.e. in different versions), this will ensure that the correct version will be executed

*'''<code>--saveSuite <fileName></code>''' saves the generated as-hoq suite. Useful if you want to archive such a dynamically generated scatter-gather suite separately from the result file(s), or to automatically construct new suites. Notice that the ".elf" result file will always include the generated ad-hoq suite, so archival of the generated ad-hoq suite is only needed if you generate pdf, html or other non-elf reports.

==== Test Parameters ====

*'''<code>--parameter <fileName></code>''' / '''<code>-P <fileName></code>''' Load a parameter set from a file. A parameter set contains values for a test suite's top environment. This can be either in XML format, as generated with the [[Environment_Editor|"''Save-Parameter-Set''" menu function]], a CSV file, containing key-value pairs or a JSON file containing a JSON dictionary object.Parameter files in either format can be created manually in a text editor, provided by a QM system (such as expeccoALM, HP Quality Center or similar), generated by another controlling program or generated by expecco itself via the "''Save-Parameter''" menu function of the [[Environment_Editor|environment editor]].The parameter file may contain values for a subset of the environment variables. In this case, the values from the parameter file overwrite corresponding values present in the loaded test suite, leaving other values unchanged.

*'''<code>--parameter:<key>=<value></code>''' / '''<code>-P:<key>=<value></code>''' Sets an individual parameter for the next "--execute" argument.If multiple "--execute" arguments are given (i.e. multiple suites are to be executed in sequence), these parameter values are collected and given to the next execution only, and overwrite corresponding values from either a parameter set (see above) or from the suite itself.Thus, it is possible to execute the same suite with different parameters in one command line (see example above). (this option is available with expecco vsn >= 2.10)

==== Test Execution via Scripting ====
*'''<code>--scriptFile <fileName></code>''' read and execute a script from a file (see scripting below).

==== Reporting ====

*'''<code>--verdicts</code>''' Send execution and result info in human readable format to the stderr output. (see [[#Verdicts Example|example below]].)

*'''<code>--logFile <fileName></code>''' Used to change the name of the generated log file, where stderr is written to. This is only useful if running in server mode.

*'''<code>--exitCode <n></code>''' Defines the exit code to be used independent of the test outcome. The default is 0 (zero) if all tests pass, and non-zero when they do not. However, some calling programs (make/jenkins,...) may misinterpret this exit code and treat the whole job as non-executable. Use this flag to prevent this. It is still possible to change the exitCode for a particular outcome by adding one of the following options after this option.

*'''<code>--exitCodeOnFail <n></code>''' Defines the exit code in case any test ends with a test-failure status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute. This option also changes the exitCodeOnError and exitCodeOnInconclusive values (see below), unless explicitly defined by those options.

*'''<code>--exitCodeOnError <n></code>''' Defines the exit code in case any test ends with a test-error status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute. This option also changes the exitCodeOnInconclusive values (see below), unless explicitly defined by that option.

*'''<code>--exitCodeOnInconclusive <n></code>''' Defines the exit code in case any test ends with an inconclusive status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute.

*'''<code>--elfReportFile <elfFilename></code>''' Writes a report in expecoo's native XML logfile format. The report contains a lot of detail information and could be processed by an XSLT processor or a similar tool. It also contains enough additional information about test plans and actions so that expecco can redisplay the activity log tree from this file. The generated file can be opened directly via the command line ("expecco <file>.elf") or by double clicking on the elf-file in the operating system's desktop.

*'''<code>--csvReportFile <csvFilename></code>''' Writes a summary report in CSV format. Each row consists of: 
** ''TESTSUITE'' - the filename
** ''TESTPLAN'' - the test plan
** ''TESTCASE'' - the test case
** ''VERDICT'' - the test result; one of SUCCESS, FAILED, ERROR or INCONCLUSIVE
** ''INFO'' - additional info in case of failure
:Additional pseudo verdicts such as STARTTIME, ENDTIME etc. are written. A typical CVS output file can be found in the [[#CSV File Example|examples]].

*'''<code>--textReportFile <textFilename></code>''' Writes a summary report in a human readable textual format. A typical text output file can be found in the [[#Textual File Example|examples]].

*'''<code>--xmlReportFile <xmlFilename></code>''' Writes a report in XML format. The report contains a lot of detail information and could usually be processed by an XSLT processor or simular tool. A typical XML output file can be found in the [[#XML File Example|examples]].

*'''<code>--pdfReportFile <pdfFilename></code>''' Writes a summary report in pdf format.

*'''<code>--htmlReportFile <htmlFilename></code>''' Writes a summary report in html format.

*'''<code>--junitReportFile <htmlFilename></code>''' Writes a summary report in a junit compatible XML format. Useful, when expecco is to be started by jenkins or similar driver programs.

*'''<code>--polarionReportFile <htmlFilename></code>''' Writes a summary report in an XML format which is especially suited for the Polarion QM tool. The structure of the generated XML is the same as with the junit format above, but a slightly different time format is used.

*'''<code>--reportTemplateName <name></code>''' Use the given report template (must be an element inside the test suite) for the following "--xxxReportFile" argument. If no such argument is given, the default template as defined in the suite is used.

==== Services ====

*'''<code>--server</code>''' Starts expecco in server mode. This combines the "''--service''", "''--infoService''" and "''--remoteControlService''" flags. All of those services as described below are started with that single command line argument.

*'''<code>--service</code>''' Starts expecco in server mode. In this mode, HTTP-SOAP and HTTP-REST requests can be used to remote-control expecco's execution; especially, to execute and monitor tests, and upload results. The most obvious use for this is for expecco to act as an execution host (test slave) for an expeccoALM or Polarion server. However, because standard protocols are used, this may also be used to interface the execution engine to many other QM management or automation systems (e.g. HP Quality Centre). The interface is described below.

*'''<code>--infoService</code>''' Provide an additional info service which allows for monitoring and control of an expecco server via a web browser (server mode only).

*'''<code>--remoteControlService</code>''' Provide an additional service to interact with a running test. Dialog requests, single stepping, starting, pausing and stopping of tests is possible via remote REST requests. This service is used by the Android remote control app, which is available upon request (server mode only).

*'''<code>--port <portNr></code>''' Used to change the HTTP and SOAP port numbers, when running in server mode. The default is 9090 (server mode only).

*'''<code>--scripting <portNr></code>''' Enable scripting (remote control via Telnet ascii interface) on portNr ([[#Scripting Example|see more below]]).

*'''<code>--allowHost <hostName></code>''' Allow hostName to connect to the scripting port. Repeat for multiple hosts (see more below).

==== Utility Functions ====

*'''<code>--diff <file1> <file2></code>''' Print differences between two test suites. This can be used eg. to automatically generate log messages for a revision control system (please read the section on "Integration with Source Code Management System" below). (This function is only available in release ≥ 2.7)

=== Command Exit Status ===

*0 - all tests passed

*>0 various other errors (command line, file not found, etc.)

*101 - at least one test failed (FAIL status). This exitCode can be overwritten by a command line argument.

*102 - at least one test was inconcusive (INCONCLUSIVE status). This exitCode can be overwritten by a command line argument.

*103 - at least one test lead to an error (ERROR status). This exitCode can be overwritten by a command line argument.
 
The diff option returns 0 if the compared suites are the same, or 200+n, (where n is the number of differences) otherwise.

== Sample Outputs ==

The following output files were generated by executing the test suite from the file:
:"C:\Programme\exept\expecco\testsuites\projects\Example.ets"
which contains a single test plan named:
:"Example Testplan"
which contains three test cases named:
:"Test1"
:"Test2"
:"Test3-Should fail"
of which the first two are supposed to PASS and the last one generates an ERROR.

All timestamp information is written in ISO8601 format.

Be reminded that the following reports are condensed reports, which only contain a subset of the information contained in expecco's native ".elf" file format. The "elf" file contains all of the execution, trace and data-flow information and the original suite as executed. "elf"-files can be reloaded at any time into the expecco UI and the test be reexecuted. Also, any of the other reports can be regenerated, posyibly with different report options (i.e. detail).

Thus it is highly recommended that these "elf" files are archived after a test run, in addition to any of the condensed report files (eg. pdf or junit report).

=== CSV File Example ("<code>--csvReportFile</code>" option) ===

By default, entries are separated by ";"-characters. Additional double quotes (") are used to delimit strings with embedded ";" or spaces. Any double quote within such a string is doubled.
CSV is a simple and very common interchange format.
For example, CSV files can be imported into Microsoft Word, Exel and Openoffice (and many other).

TESTSUITE;TESTPLAN;TESTCASE;VERDICT;INFO
;;;StartTime;2008-10-31T08:57:13.689
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test1;PASSED;
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test2;PASSED;
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";"Test3 - Should fail";ERROR;
;;;EndTime;2008-10-31T08:57:18.746

=== XML File Example ("<code>--xmlReportFile</code>" option) ===

<SummaryReport>
<StartTime>2008-10-31T08:56:49.774</StartTime>
<TestSuite>
<File>C:\Programme\exept\expecco\testsuites\projects\Example.ets</File>
<TestPlan>
<Name>Example Testplan</Name>
<TestCase>
<Name>Test 1</Name>
<Verdict>PASSED</Verdict>
</TestCase>
<TestCase>
<Name>Test 2</Name>
<Verdict>PASSED</Verdict>
</TestCase>
<TestCase>
<Name>Test 3 - Should fail</Name>
<Verdict>ERROR</Verdict>
</TestCase>
</TestPlan>
</TestSuite>
<EndTime>2008-10-31T08:56:55.142</EndTime>
</SummaryReport>

This is not to be confused with the "elf" result file format, which is also XML based, but contains a lot more detail.

Notice also, that the junit report format ("<code>--junitReport</code>" option) is similar in structure but uses different tags.
Junit reports are compatible to reports generated by Java jUnit frameworks.
They can thus be used to generate reports and trends in Jenkins/Hudson and other tools which understand the jUnit report format.

=== Textual File Example ("<code>--textReportFile</code>" option) ===

Test Execution Summary
Start: 2008-10-31 08:56:12.751
TestSuite: "C:\Programme\exept\expecco\testsuites\projects\Example.ets
TestPlan: Example Testplan
Test 1 ....................... PASSED
Test 2 ....................... PASSED
Test 3 - Should fail ......... ERROR
Finish: 2008-10-31 08:56:18.009



=== Verdicts Example ===

the "<code>--verdicts</code>" option generates a simple trace on the standard error (to be redirected into a file):

C:\selftest\commandLineArgs> expecco --noBanner --noTray --verdicts
--parameter paramesForTest.xpar --execute parameterTest.ets 
Expecco [info]: start testSuite "parameterTest.ets"...
Expecco [info]: using parameters "paramesForTest.xpar"...
Expecco [info]: start testPlan "Test Parameters From CommandLine"
Expecco [info]: start testCase "Validate Parameters"
Expecco [info]: done testCase "Validate Parameters"; STATUS=PASSED
Expecco [info]: done testPlan "Test Parameters From CommandLine"; STATUS=PASSED
Expecco [info]: done testSuite "parameterTest.ets"; STATUS=PASSED

== Integration with Quality Managament and Automation Tools ==

=== Integration with Jenkins ===

To have expecco tests being executed automatically by Jenkins, take the following example as a guideline. This is a real world setup, taken from our own setup within eXept.

# Create a test job, which is triggered by a successful build (or a change in the test suite repository)
# Check the "Block Build while prerequisite Jobs are Active" flag
# Check either the "Trigger from Source Code Management" or the "Trigger from other Job" flags
# Check "Abort build if it is Stuck" (just to make sure, that a faulty suite does not block Jenkins)
# Check "Fail the Build if Stuck" and give it a reasonable elastic Time-out Strategy (we use 300% of the last 10 builds, to make sure a longer execution time due to more test cases will not be interpreted as a stuck, and an extra timeout of 30 minutes. The timeout is very generous for the expected execution time of a few minutes).
# Check "Run xvnc during Build" to allow for monitoring, what is going on. This is also required, if the test needs a UI.
# Define the "Build Procedure" as "Execute Shell Script" (Unix/Linux) or "Execute Batch Job" (Windows)
# Enter a build procedure similar to the ours, which is:
#::<code>cd exept\expecco\application
#::del *.junit
#::expecco.com --noBanner --exitOnInternalError --noTray \
#::::--jUnitReportFile selfTestResult.junit \
#::::--execute ..\projects\expecco\eXpeccoSelfTest.ets
#::expecco.com --noBanner --noTray \
#::::--jUnitReportFile CommunicationWithExpeccoNETResult.junit \
#::::--execute ..\projects\expecco\CommunicationWithExpeccoNET.ets</code>
#:The details (especially paths and names) will of cause be different in your setup. The above uses the relative paths as it first changes the current directory to where the previous build has compiled the executable, which will of course not be the case in your setup.
# Define a "Post-build Action"
# Check "Publish Junit Test Results"
# Enter a path expression to declare the location of the resulting reports. Here, we used:<PRE>exept\expecco\application\*.junit</PRE>
# Check the "Publish Test Attachments" flag, so the results will be presented in the Jenkins management console

That's it! Because expecco has been told to generate jUnit compatible report files, we can use Jenkins' existing jUnit support. However, the jUnit xml format does not support the full range of information which is present in the native expecco result files (especially the activity log and pin value information is not included). Therefore, it is a good idea to also generate a regular ".elf" (expecco log file) and add it to the archived build artefacts.

=== Integration with expeccoALM ===
Expecco and ExpeccoALM (formerly called "''expeccoNET''") have been originally designed to work together. Therefore, only a minimum setup is required:
# ensure that an expecco test execution slave is running on each test host (server farm, virtual machines, etc.). Depending on the operating system, this is either done by installing expecco as a service (Windows), or by adding appropriate startup actions to your "init.d" files (Unix).
# define the test host(s) in expeccoALM.
# (optionally) define the devices available and attached to the execution slave machine in expeccoALM

ExpeccoALM will ask the expecco slaves about their operating system environment. So jobs will be automatically executed on matching CPU/OS machines. However, if tests require special resources (devices) to be attached, these must be defined and listed in expeccoALM as well. If your test has corresponding resource-requirements defined (see resources/inventory), expeccoALM will both ensure that the test will execute on the correct machine, and also reserve the resource during the execution. Also, test scheduling, if defined to be automatic, will be optimized to minimize resource usage, and to ensure that a higher number of tests can be executed in parallel.

=== Integration into a SOA Infrastructure ===

For this, expecco should be started on the test host(s) in so called "slave" mode.
In this mode, expecco awaits for execution commands via SOAP or REST, executes tests in the background and returns status information (progress) and results (reports).

Because tests may execute for a long time (hours or even days), the execution is performed asynchonously; first, the test has to be downloaded to the slave, then execution started. The start-command returns a ticket, which is a test-run-identifier, by which the execution progress can be queried (polled) while the test is running. Finally, a "finished" status is returned, upon which the result can be aquired via another service call.

Multiple such test slaves can be started on multiple machines, and each test slave may (if required) execute multiple tests in parallel (although this is usually limited to one, to avoid conflicts when external resources are accessed).

To start expecco in slave mode, use the command line:
expecco --service

or, if the default port (9090) is not available, use:
expecco --service --port 9090

The service interface is described below; typically, you can talk to expecco via:
http://localhost:9090/expeccoService
or:
http://localhost:9090/expeccoService/rest

The SOAP wsdl is returned via:
http://localhost:9090/wsdl/ExpeccoSOAPService.wsdl

and - if the inforService is also running - general status information with:
http://localhost:9090/info

=== Integration with HP Quality Center ===

This is described in the [[ HP Quality Center Plugin ]] document.

=== Integration with Polarion ===

This is described in the [[ Polarion Plugin]] document.

== Integration with Source Code Management Tools ==

=== Background Info on what is Contained in a ".ets" File ===

Expecco stores testsuites in a file with '.ets' extension (which stands for: "''Expecco-Test-Suite''") and result logs in '.elf' files (stands for: "''Expecco-Log-File''").
These are technically zip files - i.e. a bundle of individual files which can be extracted with the common zip command line tool (winzip under Windows systems, zip/unzip under Unix systems).

For example, "<code>unzip -l foo.ets</code>" lists the individual components, of which especially the block descriptions and attachments may be of interest.

Notice, that you have to be careful when ets-files are bundled with zip manually: for various consistency checks, expecco generates a validation signature of the components and saves this as an additional file inside the .ets file.
This signature file must be preserved and it must be consistent with the other zip-components. In effect, this means that an ets can only be constructed from the very same components, using the very same signature file as were extracted before. Otherwise, expecco refuses to load the ".ets" file later.

=== Version Management of ".ets" files ===

Unless a QA system like "expeccoALM" is used, ets-files can be stored and maintained in any other source code management (SCM) system, for example, CVS, SVN, hg/Mercurial, git, Perforce etc.
Make sure to store the .ets as binary file, and/or disable source expansion of version tag lines (for example, "$Header" or "$Id" in CVS). Consult your particular SCM system's documentation on how this is done.

As an alternative, it is possible to unzip the ets into individual components, store them separately, and zip them back into an ets, when a previous version is extracted from the SCM system. However, you must be careful to preserve the contents exactly as is, including the signature and other meta data, and not mix versions. I.e. all individual component files must be checkedIn/out in sync and as a group - it is not possible to update individual files from previous versions. The reason is that action blocks are referred to by their versionID, and these IDs will certainly be inconsistent, when previous versions of individual action blocks are mixed into another version's suite.

If, for whatever reason, you must checkin individual action blocks, we highly recommend to check in BOTH the bundled ets (and use that for later test execution), AND check in the individual components, and use only those for meta actions, such as comparison, documentation or other administrative tasks.

=== Generating Diff Lists or other Version Information ===

Many source code management systems allow for hook-scripts to be added to checkin/checkout actions, and/or to redefine the command to be used for diff-list generation.

For example, in the SVN system, an external diff tool can be defined. You could write a little shell or batch script, which calls expecco with the "<code>--diff</code>" option which is described above. Thus, you would get meaningful diff output even from checked in ets-bundle files.

The "<code>expecco --diff</code>" option is also useful as a command line tool to get diff lists - even if your SCM system does not allow for such automatic hooks.

== Scripting ==

Expecco can be scripted either by reading a script from a file or remote controlled via a telnet like command-line interface.
This is useful to execute complex test scenarios and meta tasks, to create or manipulate test suites automatically and for self-testing expecco by using another expecco to control its GUI.
It can also be used to execute and automate more complex scenarios without using expeccoALM.
 Example uses are:
* Sequentially load and/or execute all suites found in a folder, reimport libraries, save the updated suite
* Construct new suites by merging/selecting tests from other suites
* Bulk renaming, commenting, attributing etc.
* Change attachments inside a number of suites
* Controlling an application or web interface (via a GUI plugin) and saving a sequence of screen shots

By default, the scripting interface expects expressions in JavaScript syntax (but with a Smalltalk object model),
similar to the language used for elementary block definition. However, the language can be changed to Smalltalk syntax via a "~" directive.

=== Script File Example ===

To control expecco via a scriptfile, use the "<code>--scriptFile <filename></code>" command line argument, where <filename> must be a file containing JavaScript expressions.

For example, the following script file named "run3Suites.js" may contain the code:
<PRE>
// Example for an automatic expecco script.
// (loads and executes a number of test suites)
//

// to enable debugging in case of an error.
// STXScriptingServer.errorDebugging(true);

var files = [
"foo.ets",
"bar.ets",
"baz.ets",
];

Expecco::ExpeccoPreferences.current.automaticReimportOnLoad(true);
Expecco::ExpeccoPreferences.current.checkForReimportableImportsOnLoad(true);
Expecco::ExpeccoPreferences.current.checkForAnchestorOnAutomaticReimport(false);
// Expecco::ExpeccoPreferences.current.libraryPath(importPathes);

// --------------------

function executeTestPlan ( aTestPlan ) {
Stderr.nextPutLine("executing testplan "+aTestPlan.name()+"...");
resultList = aTestPlan.execute();
Stderr.nextPutLine("done.");
}

function runSuite(suiteFile) {
var loadedProject;

Stderr.nextPutLine("loading "+suiteFile+"...");
expecco.loadProjectFromFile(suiteFile);
loadedProject = expecco.project();

if (loadedProject == null) {
Stderr.nextPutLine("failed to load library "+suiteFile+".");
Smalltalk.exit(1);
} else {
loadedProject.allTestPlansDo( executTestPlan );
}
};

files.do(runSuite);
</PRE>

And can be executed with:

expecco --scriptFile run3Suites.js

for windowless operation, use the "<code>--noWindow</code>" command line argument.
To speed up the startup, you can turn off the loading of plugins, with a "<code>--noPlugins</code>" argument (and possibly load any required plugins explicitly via additional plugin arguments).
Finally, enable debug messages with a "<code>--debug</code>" argument.
Thus, the recommended options for scripting are:

expecco --debug --noPlugins --noWindow --scriptFile run3Suites.js

of course, this command line can be put into a shell (or batch) script file, and then executed with a single word command.

=== Telnet Scripting Example ===

The remote scripting service is enabled when a "<code>--scripting</code>" command line argument is given.
By default, the service only accepts connections from the local host (for security reasons). Using the "<code>--allowHost</code>" option, more hosts can be gained access to the scripting feature - but be aware, that this opens a potential security hole, as all of the internal functions can be accessed via the scripting system (and this includes the possibility to write files and call operating system services with the access rights of the one who started the scripting server).

When used with a remote script connection (telnet),
additional connection- and execution related commands are introduced by lines starting with the "~" (tilde) escape character (similar to telnet).
For example, "~." (tilde-period) is used to close the connection.
Press "~?" (tilde-question) for help.

The following is a trace of a typical scripting session (user input in bold):

c:\programs\expecco> expecco --scripting 8008
c:\programs\expecco> ... expecco now running in the background with GUI ...
...
c:\programs\expecco> telnet localhost 8008
Welcome to Expecco (Type ~? for help)
> println(expecco);
an Expecco::Browser
> expecco.menuNewProject();
...expecco performs the new-function from its menu...
> expecco.loadProjectFromFile("C:\Users\cg\testsuites\webedition\projects\BearerTest.ets");
...expecco loads the testSuite...
> expecco.close();
> ~.
Lost Connection.
c:\programs\expecco>

You can also start a scripting session without an initial expecco browser window:

c:\programs\expecco> expecco --noWindow --scripting 8008
c:\programs\expecco> ... expecco now running in the background without GUI ...
...
c:\programs\expecco> telnet localhost 8008
Welcome to Expecco (Type ~? for help)
> println(expecco);
an Expecco::Browser
> expecco;
> ~v+ // turn result-printing on
> expecco
an Expecco::Browser
> ~v- // and off again
> expecco.loadProjectFromFile("~/SomeTest.ets");
...expecco loads the testSuite...
> var blk = expecco.project.elementWithName("My Action");
> blk.name("My Fun Action");
> expecco.saveProjectToFile("~/ModifiedTest.ets");
> expecco.close();
>~.
Lost Connection.
c:\programs\expecco>

== Scripting API Overview ==

A few objects are predefined by name; among them are "''expecco''", which refers to the browser itself (i.e. the UI) and "''environment''", which refers to a collection of variable bindings (this is a dictionary of interpreter variables - not to be confused with a variable environment as known inside an expecco activity block).
 New variables can be defined with a "<code>var <name>;</code>" statement. For example:
<CODE><PRE>
var ws;

ws = new ExpeccoWorkspaceApplication;
ws.open();
ws.close();
</PRE></CODE>

==== expecco Object ====

The variable named "''expecco''" refers to the opened GUI-object, which represents the expecco application itself.

===== Expecco Functions =====

*'''project()''' the current project
*'''currentApplication()''' the current page (initially, there is only one)
*'''currentTreeApplication()''' the current tree sub-application

*'''selectModelItem( anItem )''' select an item and open an editor for it
*'''selectedModelItems()''' returns a collection of selected items
 

===== Menu Functions =====
These execute the underlying menu functions (as if clicked by the user).

*'''menuNewProject()''' creates a new testSuite
*'''menuOpen()''' opens a dialog requesting a testSuite
*'''menuExit()''' closes the expecco application

*'''loadProjectFromFile(fileNameString)''' load a testSuite
*'''saveProjectToFile(fileNameString)''' save the testSuite
*'''selectTestPlanWithName(testPlaneNameString)''' select a testplan item by name
*'''selectTestPlanWithFunctionalId(uuid)''' select a testplan item by uuid

*'''testSuite()''' retrieves the testSuite object (see below)
 

===== Test Suite (Project) Functions =====
the project as returned by the above "project()" function provides access to its elements:
 (see also [[ Expecco API#Test Suite Project Functions]])

*'''authorName()''' get the author name string
*'''authorName(aString)''' set the author name string
*'''versionString()''' get the version string
*'''versionString(aString)''' set the version string
*'''projectsWorkingDirectory()''' the directory, where attachments etc. are found
*'''ensureEnvironment()''' an instantiated environment (concrete values). See below.
*'''elementWithName( nameString )''' returns a matching element or null if not found
*'''elementWithId( aUUID )''' returns that element or null if not present. (create the UUID with "<stringConstant>.asUUID" )
*'''elementWithFunctionalId( aUUID )''' returns that element or null if not present
 

==== Environment Object ====

Environment objects are used to store key-value bindings for expecco variables. Environments form a hierarchy, where values are searched for in an environment's parent environment, if not present. This hierarchy follows the containing compound activity chain up to the project (= test suite) environment.
Additional temporary environments are kept by the executor and the browser, to keep temporary values for a single execution's or a single session's lifetime.

*'''at(key)''' retrieves a value, given the name of the entry. Raises and error if no variable exists by that name.
*'''at_ifAbsent(key, default)''' like above, but returns default if no variable exists by that name (instead of raising an error).
*'''includesKey(key)''' true if a variable by that name exists, false otherwise.
*'''at_put(key, value)''' store value as variable named key. Raises an error, in an attempt to change a readOnly variable
*'''environmentDescription()''' returns the environment's description. This describes types, default values and read/write attributes per entry.
 

==== EnvironmentDescription Object ====

This is a collection of entries which describe variables of an environment. It does only hold the description, not the bindings themself; i.e. it contains the information required to instantiate an environment. EnvironmentDescriptions inherit from OrderedCollection and therefore entries are accessed via "at:" using a numeric index from 1 to the environmentDescription's size.

Entries (as per variable) provide the following protocol:

*'''name()''' the name of the variable
*'''isReadOnly()''' true if readonly
*'''defaultValue()''' the initial value, assigned when the environment is created
*'''datatype()''' the type of the variable
*'''comment()''' description
 

== Remote Controlling and Monitoring Expecco ==

Expecco itself can be automated by various mechanisms:

* via command line arguments (described in [[ #Command Line | "Command Line"]] above)

* via script files (see [[ #Script File Example | "Script File Example"]] above)

* via the telnet interface (see [[ #Telnet Scripting Example | "Telnet Scripting Example"]] above)

* via standard RPC mechanisms, such as SOAP or REST.

Especially the RPC mechanisms are useful to integrate expecco into the company test infrastructure.
Such interfaces are meant for programmatic control of an expecco slave from quality management, application life cycle and other scheduling tools.
Our own companion product, ExpeccoALM and third party tools, such as Polarion use these service interfaces.

Notice, that for integration into a Jenkins infrastructure, command line arguments or scripts may be a more cost efective means to control automated expecco testruns.

=== Expecco as a Slave Node in a Test Lab ===

The service interfaces are useful to control unmonitored slave machines in the network, among which expecco test execution jobs are scheduled by another program. ExpeccoALM and other quality management tools use these to initiate test runs in a test server farm.
For this, the basic operations "download of a suite", "execute a suite" and "requesting execution results" are available as service calls.

Both SOAP and REST services are available, if expecco is started with the "''--server''" argument.
An optional "''--port''" argument allows for the HTTP port to be changed from the default (9090) on which expecco is listening.

For debugging and testing, the service can be also be started from the interactive UI, via expecco's main menu (in the "''Extras''" - "''Web-Services''" - "''Start / Stop''" menu items).

These services use HTTP requests as transport layer.

==== Expecco SOAP Service Interface ====

This accepts SOAP requests, via the URL "<code>/expeccoService</code>". I.e. the default URL is "<code>host:9090/expeccoService</code>".
A partial WSDL spec can be aqcuired from the running service via "<code>host:9090/wsdl/ExpeccoSOAPService.wsdl</code>" (partial, because it is currently not does not contain complete type information).

The service entries are:

===== Loading and Executing a Suite =====

The execute request is the main service entry. It passes the suite and also optional parameters.

The test suite can be bade available to expecco either by passing it with the request (as base64 CDATA), or by passing a URL from which expecco can fetch the suite iteslf.

The execute call contains the following fields:

<message name="expecco_executeProject_v5_Request">
<part name="id" type="UUID"/>
<part name="testSuiteId" type="UUID"/>
<part name="dataSource" type="xsd:string"/>
<part name="dataSourceUri" type="xsd:string"/>
<part name="environment" type="xsd:arrayType"/>
<part name="testplans" type="xsd:arrayType"/>
<part name="resources" type="xsd:arrayType"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

and responds with:

<message name="expecco_executeProject_v5_Response">
<part name="result" type="xsd:string"/>
</message>

This call starts execution, and immediately returns a response, which consists of an identifier.
This identifier can later be used to ask expecco about the execution status. As a test may take a long time to finish,
it is useful to poll via status requests from time to time, to see if the execution has finished and to get progress status.

The parameters are:

* id - mandatory; a ticket ID; this should be a UUID-string, to avoid possible conflicts
* testSuiteId - mandatory; the UUID of the suite to execute. See below for details about download optimizations
* dataSource - optional; if present, this should contain the whole ets-file's contents as a Base64 encoded CDATA string
* dataSourceUri - optional; if present, this should be the URI from which expecco shall fetch the suite. See below for details
* environment - optional; top-level environment variable values. This can be used to provide alternative initial values for variables in the top level variable environment (the "Project-Environment")
* testplans - optional; a list of UUIDs of testplans to execute. If not present, all top-level testplans are executed
* resources - optional; a list of resources to be used by the test (see expeccoALM resource description)
* optionalParameters - optional; an array containing additional parameters as key-value elements.

The "optionalParameters" field:

A list of key-value elements (i.e. must have an even number of elements, of the form [k1 v1 k2 v2 ... kN vN] ).
Each key is an xsd:string, each value's type depends on the key, but all of them are currently also strings.
The list of supported parameters is open for future extension of the interface. Currently, the following are recognized:
* [ "generateLog" xsd:boolean ] - the boolean arg must be "true" or "false"
* [ "generatePDFReport" xsd:boolean ] - boolean arg, must be either "true" or "false"

The "testplans" field:

this allows selective execution of individual test plans and also individual test cases (from within a test plan) from the suite.
If not present, all test plans as present in the suite are executed.
If present, the testPlans parameter must be an xsdarray of pairs (i.e. each array element is again an xsdarray with 2 elements).
Each top level element describes one testplan to be executed. The first element of each being the testplan's UUID, the second another array, listing the testcases by UUID.
For example, if the suite contains three testplans, named "a", "b" and "c", with plan "a" having id-a and "b" having id-b as UUID.
A testPlans argument might look like:
<pre>
[
[ id-a ]
[ id-b [ id-tcb-1 id-tcb-2 ] ]
]
</pre>
and specify that testplan "a" should be executed fully (i.e. all test cases), and only the testcases tcb-1 and tcb-2 are to be executed from testplan "b".

The "environment" field:

-- to be described --

The "resources" field:

-- to be described --

The reply consists of the ticket-id, which has to be passed in further status requests.

===== Loading Only =====

It is also possible, to download a suite without execution, via the "download" request:

<message name="expecco_downloadProject_Request">
<part name="testSuiteId" type="xsd:string"/>
<part name="dataSourceBase64" type="xsd:string"/>
<part name="dataSourceUri" type="xsd:string"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

<message name="expecco_downloadProject_Response">
<part name="result" type="xsd:string"/>
</message>

===== Download Optimization =====

Expecco remembers downloaded suites in a temporary folder, to avoid repeated transfers of possibly huge test suites.
If a URI is passed (but no base64 encoded data), expecco checks if the suite is already present on the test host,
and will not fetch it again, if already present. If not present, expecco will fetch the suite via a HTTP request from the URI.

If no URI is passed (i.e. both data and dataURI fields are empty), expecco will either respond with an error reply, if not present,
or with an ok response, if already present.

Thus, if you have to pass the suite as data (i.e. there is no file service available, from which expecco could fetch the suite),
it is recommended to first check if a suite is already present (by sending a download request without data) and check for an error return. If no error is reported, the suite is already there and no further download action is required. If there is an error response,
the client should send the suite with another download request, this time with a non-empty data field.

After any successfull download (either via download, or via execute request), the suite can be executed by an execute request without data.

===== Execution by Suite File Name =====

An alternative to downloading suites is to execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.
The executeTestSuiteFile-request is used to execute one of the suites in that directory.

The call contains the following fields:

<message name="expecco_executeTestSuiteFile_Request">
<part name="id" type="UUID"/>
<part name="fileName" type="xsd:string"/>
<part name="environment" type="xsd:arrayType"/>
<part name="testplans" type="xsd:arrayType"/>
<part name="resources" type="xsd:arrayType"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

If successful, a ticketID is returned (same as above execute-request).

===== Status Request =====

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the above execute request.

<message name="expecco_getExecutionInfo_Request">
<part name="ticketId" type="UUID"/>
</message>

<message name="expecco_getExecutionInfo_Response">
<part name="result" type="xsd:string"/>
</message>

A client may have to send multiple "getExecutionInfo" requests, until a "finished" status is returned.
Expecco will keep the generated reports and log files in a temporary folder, until fetched via a getResult request.
This allows for both expecco and the client to be turned off and restarted, without loosing any status information.

===== Result Request =====

Once finished, reports and log files should be fetched from expecco.

<message name="expecco_getResult_Request">
<part name="ticketId" type="UUID"/>
<part name="removeResultBoolean" type="xsd:string"/>
</message>

<message name="expecco_getResult_Response">
<part name="result" type="xsd:string"/>
</message>

After the "getResult" request, corrsponding files are automatically removed from the temporary folder by expecco.

===== Terminate/Abort Request =====

Use this, to abort and terminate an ongoing test execution.

<message name="expecco_killExecution_Request">
<part name="ticketId" type="xsd:string"/>
</message>

<message name="expecco_killExecution_Response">
<part name="result" type="xsd:string"/>
</message>

===== Remove Ticket Request =====

Use this, to tell expecco, that no further interest exists in a ticket.
If the test is still running, it is aborted. If it is about to be started, it will not be.
Any temporary files which might have already been created due to this execution are removed.

<message name="expecco_killExecution_Request">
<part name="ticketId" type="UUID"/>
</message>

<message name="expecco_killExecution_Response">
<part name="result" type="xsd:string"/>
</message>

===== Ping =====

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

<message name="ping_Request">
</message>

<message name="ping_Response">
<part name="result" type="xsd:array"/>
</message>

===== Cleanup of Old Result/Log Files =====

This request can be used to remove all temporary files, especially leftover report- and log files.
This should be used, if a client has crashed, and lost track of

<message name="expecco_cleanupTempFiles_Request">
</message>

<message name="expecco_cleanupTempFiles_Response">
<part name="result" type="xsd:string"/>
</message>

===== Example Wire Protocol Trace =====

Client asks expecco to execute a suite.

<-- HTTP Request to Expecco --
<PRE>

POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 8925
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">

<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_executeProject_v5 xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<optionalParameters xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[6]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">generateReport</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">generateLog</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">runAllTestcasesIfEmptyTestcaseList</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
</optionalParameters>

<testSuiteId xsi:type="UUID">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<testplans
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:arrayType[1]">
<item
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
enc:arrayType="xsd:anyType[2]">
<item
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xsi:type="xsd:string">f71c4700-7477-11df-a41b-00ff7b08316c
</item>
<item
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
enc:arrayType="xsd:anyType[0]">
</item>
</item>
</testplans>
<id xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</id>
<dataSource xsi:null="1"/>
<dataSourceUri xsi:type="xsd:string">http://127.0.0.1:8662/expeccoALM/tentativeObjects/a84b2d96-d133-47db-9fc2-17208b490bfe.a
</dataSourceUri>
<environment
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[22]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Host__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">sr-laptop</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_LoginUserName__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">admin</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_FullUserName__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">. *admin*</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_TestHost__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">127.0.0.1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_UUID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">e5c9cb30-a253-11e4-9f24-c48508c91d3c</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_ID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">d4</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_Name__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Test For Resources and Skills</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_Summary__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string"></item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Run_UUID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">200d93e1-a258-11e4-b9eb-c48508c91d3c</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Run_ID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">r14</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_TestSuite_VersionNumber__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">1</item>
</environment>

<resources
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[28]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute1-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute2-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute2-2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Float</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0.0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 2 eeee</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute1-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
</resources>
</m:expecco_executeProject_v5>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco

<PRE>

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 649
Connection: Keep-Alive

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_executeProject_v5Response xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</result>
</m:expecco_executeProject_v5Response>
</env:Body>
</env:Envelope>

</PRE>

Client asks expecco for execution state

<-- HTTP Request to expecco

<PRE>

POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 635
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfo xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<ticketId xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</ticketId>
</m:expecco_getExecutionInfo>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco (while still executing)

<PRE>

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 2579
Connection: Keep-Alive

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfoResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result>
<executionResultState xsi:type="xsd:string">executingTestSuite</executionResultState>
<currentActivity xsi:type="xsd:string">executing Neuer Testplan</currentActivity>
<pdfReportFileURL xsi:null="1"/>
<summaryResult>
<summaryTestplanExecutionResults xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<summaryTestPlanItems xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<detailString xsi:null="1"/>
<resultActivityState xsi:type="xsd:string">Successful</resultActivityState>
<testplanItemName xsi:type="xsd:string">Neue Aktion</testplanItemName>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanItemExecutionResult</expeccoClass>
</item>
</summaryTestPlanItems>
<testPlanId xsi:type="xsd:string">22623ef0-757d-11df-a41b-00ff7b08316c</testPlanId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanExecutionResult</expeccoClass>
<testPlanName xsi:null="1"/>
</item>
</summaryTestplanExecutionResults>
<testSuiteName xsi:type="xsd:string">Test For Resources and Skills</testSuiteName>
<testSuiteId xsi:type="xsd:string">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestSuiteExecutionResult</expeccoClass>
</summaryResult>
<logFileURL xsi:null="1"/>
<expeccoClass xsi:type="xsd:string">Expecco::SoapExecutionResult::SummaryEncoding</expeccoClass>
<executionProgress xsi:type="xsd:integer">0</executionProgress>
</result>
</m:expecco_getExecutionInfoResponse>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco (after execution)

<PRE>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 2781
Connection: Keep-Alive

.....................
<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfoResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result>
<executionResultState xsi:type="xsd:string">finished</executionResultState>
<currentActivity xsi:type="xsd:string">executing Neuer Testplan</currentActivity>
<pdfReportFileURL xsi:type="xsd:string">http://127.0.0.1:9090/expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.pdf</pdfReportFileURL>
<summaryResult>
<summaryTestplanExecutionResults xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<summaryTestPlanItems xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<detailString xsi:null="1"/>
<resultActivityState xsi:type="xsd:string">Successful</resultActivityState>
<testplanItemName xsi:type="xsd:string">Neue Aktion</testplanItemName>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanItemExecutionResult</expeccoClass>
</item>
</summaryTestPlanItems>
<testPlanId xsi:type="xsd:string">22623ef0-757d-11df-a41b-00ff7b08316c</testPlanId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanExecutionResult</expeccoClass>
<testPlanName xsi:null="1"/>
</item>
</summaryTestplanExecutionResults>
<testSuiteName xsi:type="xsd:string">Test For Resources and Skills</testSuiteName>
<testSuiteId xsi:type="xsd:string">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestSuiteExecutionResult</expeccoClass>
</summaryResult>
<logFileURL xsi:type="xsd:string">http://127.0.0.1:9090/expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.elf</logFileURL>
<expeccoClass xsi:type="xsd:string">Expecco::SoapExecutionResult::SummaryEncoding</expeccoClass>
<executionProgress xsi:type="xsd:integer">100</executionProgress>
</result>
</m:expecco_getExecutionInfoResponse>
</env:Body>
</env:Envelope>

</PRE>

Client fetches the report and log files from expecco:

<-- HTTP Request to expecco (fetch logfile)

<PRE>
GET /expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.elf HTTP/1.1
Connection: Keep-Alive
User-Agent: Mozilla/3.0N
Host: 127.0.0.1:9090
Accept-Encoding: chunked
Accept-Language: en,*
Accept-Charset: iso-8859-1,*,utf-8
Accept: */*
</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: application/x-expecco-logfile
Content-Length: 12690
Connection: Keep-Alive
Cache-Control: max-age=86400
Last-modified: Thu, 22 Jan 2015 17:32:50 GMT

... a lot of elf-file data ...
</PRE>

<-- HTTP Request to expecco (fetch pdf report)

<PRE>
GET /expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.pdf HTTP/1.1
Connection: Keep-Alive
User-Agent: Mozilla/3.0N
Host: 127.0.0.1:9090
Accept-Encoding: chunked
Accept-Language: en,*
Accept-Charset: iso-8859-1,*,utf-8
Accept: */*
</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 29768
Connection: Keep-Alive
Cache-Control: max-age=86400
Last-modified: Thu, 22 Jan 2015 17:32:51 GMT

... a lot of pdf data ...
</PRE>

Client releases ticket (so expecco can remove the temporary data)

<-- HTTP Request to expecco

<PRE>
POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 627
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_removeTicket xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<ticketId xsi:type="UUID">ad8011e1-a25c-11e4-b9eb-c48508c91d3c</ticketId>
</m:expecco_removeTicket>
</env:Body>
</env:Envelope>

</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 614
Connection: Keep-Alive

.....................
<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_removeTicketResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result xsi:type="xsd:boolean">true</result>
</m:expecco_removeTicketResponse>
</env:Body>
</env:Envelope>

</PRE>
===== Example Session Using "<code>wget</code>" =====

Using "wget" with SOAP is possible, but a little complicated, because correct SOAP requests have to be constructed, and ticket-numbers be extracted from responses. It is much easier with the REST service.

See below for a description.

==== Expecco REST Service Interface ====

This accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

The REST service supports the same set of operations as the SOAP service described above, but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are all HTTP-GET requests, possibly with attached JSON encoded argument data.
The operation is determined by the URI: the last component is the operation name to be executed.

See details [[ Starting_expecco_via_Comand_Line/rest/en | "expecco rest service interface"]].

===== ProtocolInfo Request "/expeccoService/rest/protocolInfo" =====

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE"; currently always "GET"
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

{
"URLPath" : "expeccoService/rest" ,
"Service" : "ExpeccoRestService",
"Version" : 1 ,
"Protocol" :
[
{
"Name" : "execute" ,
"Request" : "GET" ,
"Argument" : "(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "start execution; return ticketID." ,
},
{
"Name" : "download" ,
"Request" : "GET" ,
"Argument" : "(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "start execution; return ticketID." ,
},
{
"Name" : "executeTestSuiteFile" ,
"Request" : "GET" ,
"Argument" : "(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "execute suite file; return ticketID." ,
},
{
"Name" : "getExecutionInfo" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Return" : "Dictionary"
"Comment" : "get execution status of an execute job; argument is ticketID." ,
},
{
"Name" : "killExecution" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Comment" : "kill execution of an execute job; argument is ticketID."
},
{
"Name" : "removeTicket" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Comment" : "give up execution of an execute job; if required, kill the job. argument is ticketID."
},
{
"Name" : "cleanupTempFiles" ,
"Request" : "GET" ,
"Comment" : "remove leftover temporary files."
},
{
"Name" : "ping" ,
"Request" : "GET" ,
"Comment" : "test reachability and return some status info." ,
"Return" : "Dictionary"
},
{
"Name" : "protocolInfo" ,
"Request" : "GET",
"Return" : "Dictionary"
}

]
}

===== Execute Request "/expeccoService/rest/execute" =====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

===== Download Request "/expeccoService/rest/download" =====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.

===== Execute File Request "/expeccoService/rest/executeTestSuiteFile" =====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

The file must be present/reachable by the expecco slave.
It may be either an absolute pathname (typically on a shared network drive) or
a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

===== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" =====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

===== KillExecution Request "/expeccoService/rest/killExecution" =====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

===== RemoveTicket Request "/expeccoService/rest/removeTicket" =====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

===== Cleanup Request "/expeccoService/rest/cleanupTempFiles" =====

No argument. no return value.

===== Ping Request "/expeccoService/rest/ping" =====

No argument. Returns an object containing status information.

 

===== Example Wire Protocol Trace =====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>

===== Example Session Using "<code>wget</code>" =====

Using "wget" with SOAP is possible, but a little complicated, because correct SOAP requests have to be constructed, and ticket-numbers be extracted from responses. It is much easier with the REST service.

Assuming, you have a folder containing 3 suites "suiteA.ets", "suiteB.ets" and "suiteC.ets", and you want to send them to a running expecco slave via REST, here is how to do it:

1) to check if the expecco slave is up and running, send it a

=== Expecco Remote Control REST Service Interface ===

A secondary REST service is available to interact with a running test.
This service is used by the "expecco remote control App", which is available for Android devices (tablets and cell phones).

This accepts REST requests, via the URL "/remote". I.e. the default URL is "host:9090/remote".
A description of the supported REST calls can be aqcuired from the running service via "host:9090/remote/protocolInfo".

When this service is active, the standard Dialog requests (input boxes, with "OK"/"Cancel" buttons) will also be presented on the remote controlling app, and can be answered either on the PC-screen OR on a remote android device.
An obvious application of this is when the test system (hardware) needs manual interaction and you have to leave the workplace for this. Here, it is very convenient to be able to answer questions like "Insert Cable X and press OK to proceed" from a mobile device. Avoiding the need to walk back to the workplace to click on the "OK" button.

=== Expecco Short Status Information Service ===

This is a very simple HTTP service, which delivers a single page with a status overview.
This service is started when the "<code>--infoService</code>" or "<code>--server</code>" command line arguments are present.

This accepts HTTP requests, via the URL "/info".
I.e. the default URL is "<code>host:9090/info</code>".

The main use of this service is to quickly check the status of a testslave from a remote webbrowser,
without a need for a more complicated SOAP or REST service client.

Back to [[Online_Documentation#Topic:_Execution | Online Documentation]]

Starting expecco via Command Line/en

2017-04-02T12:43:32Z

Ab:

== Introduction ==

expecco can be started manually via the command line, by batch or shell scripts or automatically via the crontab (Unix) or scheduled tasks / services (Windows) mechanism of the operating system. Thus, you can have tests to execute unattended and without GUI "overnight". This is also the method to integrate expecco with other quality tools, such as Jenkins, HP-Quality Center, Polarion, expeccoALM etc.

Command line options allow for test suites to be loaded, executed and result files being generated without requiring user interaction.

In addition to the above, expecco can also be started in a slave mode as a service, to wait for incoming test-run request from a QM system, such as expeccoALM or Polarion. Expecco can respond to request via SOAP or REST calls to load, execute and report test suites. The expeccoNET automation environment assumes that expecco is already running on each slave host, and each has been started with a "--server" command line argument. It uses HTTP+SOAP/REST to communicate with those expecco slaves by default.

In this later "slave mode", expecco is installed to run as a daemon process (under Unix) or as a service (under Windows), and will be automatically started by the operating system, when it boots. The details of how it is installed vary between operating systems: under Unix, it needs to be registered in the init-tab-folder, under Windows it needs to be installed as a Windows service.

== Command Line ==

If expecco is started without command line arguments, it will open up showing the initial welcome screen. The same behavior as if started via the desktop.

With a single file argument, expecco will read a test suite from the given file and open an editor window on it (but will not execute it).

'''expecco <testsuite filename>'''

This is the same behavior as if a test suite file (.ets) is dropped onto the expecco icon via the desktop.

The simplest command line to execute a test suite is:

'''expecco --execute <testsuite filename> ...'''

:<testsuite filename> is the test suite's filename, as saved from within the expecco GUI application. This should be a saved ".ets" testSuite file. If more than one test suite filename is given, each is processed in sequence. All top-level test plans as found in the test suite(s) are executed (see below for more options).

:By default, the overall execution outcome is returned by the command's return value (exit code), which is
::0 - all PASSED
::non-zero - any ERROR, FAILURES or INCONCLUSIVE items.

The return value is useful if expecco is started via a makefile, or from jenkins for example. If the caller needs a different exit code, use one of the exitCodeOnXXX options as described below. This is useful to avoid a ''make'' or ''jenkins'' process from stopping.

To get a list of available options, type:
'''expecco --help'''

=== Command Line Options ===
Command line options are handled at two places: the runtime system (Smalltalk/X VM) and the expecco application itself.
When expecco is started, the VM is first to look for command line arguments and processes any of the VM options, until
a non-VM option is encountered. It passes the remaining options to expecco's main entry.
Thus, any option which is given after the first non-VM option will not be handled by the VM, but by expecco. Therefore, no VM options should be placed after the first non-VM option. VM options are marked as "''VM option''" in the list below.

Also, some options are specific to the operating system, on which expecco is executed. These are marked as "''Windows''", "''Linux''" etc.

=== Recommended Command Line Options ===

To start expecco on an existing test suite, use:

'''expecco <testsuite filename>'''

this is also the way expecco is started, when a test suite file is double-clicked on the Linux or Windows desktop, or when a test-suite document is dropped onto the expecco icon.
The above opens the expecco GUI and loads the given test suite initially. However, it does not automatically execute any test.

To execute a suite, add a "'''--execute'''" argument (or in expecco 2.10, "-E"), as in:

'''expecco --execute <testsuite filename>'''

You will notice, that expecco shows a banner intitially; this can be disabled with a '''--noBanner''' option. Also, under windows, a small tray icon is shown in the lower right, which provides a controlling UI. This is disabled with '''--noTray'''.

Finally, as mentioned before, the test's outcome is reported via the exit code. If you want a little more information on the status of individiual test cases, use a '''--verdicts''' option.

This makes the following a good start for your command line:

'''expecco --noBanner --noTray --verdicts --execute <testsuite filename>'''

or, if you want to use a special parameter-file, to provide values for (some of) the project-variables:

'''expecco --noBanner --noTray --verdicts --parameter <param-file> --execute <filename>'''

Parameter files are XML, CSV or JSON-files containing key-value pairs. They are usually created by saving an environment from within the expecco GUI (see [[Environment Editor]]).

All of the above command lines opened an expecco UI window.
To execute a suite without GUI, add a "'''--noWindow'''" argument.

To compose "scatter-gather" test cases from possibly multiple suites, found in a directory use:

'''expecco --suiteDirectory <dirName> --testCaseNames "T01,T02,T05" --execute'''

or, to explicitly specify the suite-files where test cases are taken from, use:

'''expecco --testCaseNames "T01,T02,T05" --execute <suiteFile1>.ets <suiteFile2>.ets ...'''

Finally, to get a report, add a "'''--xxxReportFile <fileName>'''" argument, as in:

'''expecco --noBanner --noWindow --noTray --verdicts --parameter <param-file>''' \
''' --pdfReportFile result.pdf --execute <filename>'''

All options are described in more detail below.

=== Executing Multiple Test Suites in Sequence ===

It is possible to run multiple (possibly different) test suites with one command line to reduce startup and project loading times.
For this, provide multiple "--execute <filename>" arguments to the command line, as in:

'''expecco --execute <suiteFile1>.ets --execute <suiteFile2>.ets ...'''

with this command line, expecco first executes the toplevel testplan(s) from "suiteFile1.ets", then those from "suiteFile2.ets". All parameters (i.e. top-level variable values) will be taken from within the corresponing suite file.

To change individual parameters, use "--parameter:key=value" arguments before the corresponing --execute argument. For example, to execute the same suite with different parameters, use a command line like:

'''expecco --parameter:device=samsung --execute mobileTest.ets''' \
''' --parameter:device=nexus --execute mobileTest.ets'''

=== Opening a Previous Result File ===

As described below, expecco can generate result files in various formats and different detail. The pdf, html and junit outputs will contain summary information to be read by humans, archived or to be passed to other programs (eg. to jenkins for statistics).

The native result file (.elf) contains all trace and logging information including the original test suite.

As such, it can be archived to ensure that the test result can always be associated to the exact suite being executed, even if the suite file is lost or has been modified in the meanwhile.

These .elf result files are generated either via corresponding command line options or manually via the "''Test Results''"-"''Save Result As...''" menu item.
Like regular suite files, they can be opened via the command line or via the "''File''"-"''Open...''" menu item.

When opened, the original suite (at the time of execution), the trace- and log data and the execution times will be presented. It is even possible to re-execute individual blocks, test plans or the whole suite.

This feature is very powerful, in that it allows for the result file to be given to a developer and will help to analyse the data values, control flows and even to rerun tests and reproduce errors/failures.

=== Detailed Option Description ===

==== Information/Debugging/Logging ====

*'''<code>--help</code>''' Prints an up-to-date list of possible options and command line arguments.

*'''<code>--version</code>''' Prints the expecco release identification and exits.

*'''<code>--noBanner</code>''' (''VM option'') Suppress the splash startup banner.

*'''<code>--console</code>''' (''VM option'', ''Windows only'') Open a debug console window for Stdout and Stderr.

*'''<code>--verbose</code>''' (''VM option'') Additional startup, execution and result info is sent in human readable format to the stderr output. This is mainly meant to analyze startup problems and is actually more useful for expecco developers. It may be too much of printout, so try "''--verdicts''" instead.

*'''<code>--debug</code>''' Turns on startup debugging. By default, if an error occurs during startup, expecco terminates itself. With this option enabled, a command line debugger is opened instead. This is probably only useful for plugin developers.

*'''<code>--silent</code>''' Suppresses most info, warning and error messages which are sent to stderr/stdout. This is mainly meant to remove unwanted informational messages (for example, when plugins cannot be loaded during startup, etc.). (this option is available with expecco vsn >= 2.10)

==== Startup ====

*'''<code>--settings <fileName></code>''' Force using <fileName> instead of the default "<code>~/.expecco/.expeccoPreferences</code>" to be used for the settings file name. Useful if you want different setups to be linked to different desktop icons, or to start expecco with particular settings from a batch or shell script. To generate a preferences file, open the "''Extras''" - ''Settings''" dialog, change the settings as required, and select the "''File''"-"''Save As...''" menu item.

*'''<code>--licenseFile <fileName></code>''' Use this license, instead of the default "<code>~/.expecco/.expeccoLicense</code>". If a license server (floating licenses) is used, the license server's hostname and port information is read from the settings file.

*'''<code>--licenseServerHost <hostName></code>''' Use this host as license server, instead of the one specified in the settings file (or if no settings file was ever specified). This may be needed when running expecco as a test slave (daemon or service). (this option is available with expecco vsn >= 2.10)

*'''<code>--licenseServerPort <portNr></code>''' Use this port-nr when contacting the license server, instead of the one specified in the settings file (or if no settings file was ever specified). This may be needed when running expecco as a test slave (daemon or service). (this option is available with expecco vsn >= 2.10)

*'''<code>--noTray</code>''' (''Windows only'') Disable the tray control icon (server and execute modes only).

*'''<code>--tray</code>''' Force a tray window to be shown, even if running in non-server (slave) mode. The tray window displays the current execution status, memory situation, thread status and other internal information, which is probably only useful for developers. (this option is available with expecco vsn >= 2.10)

*'''<code>--noWindow</code>''' Do not open the main window (useful when scripting or executing only).

*'''<code>--noDisplay</code>''' Do not open any window (useful when scripting or executing only).

*'''<code>--noPlugins</code>''' Disable plugin loading. This makes startup somewhat faster, depending on the number of plugins found in your installation directory. You can still force individual plugins to be loaded using the "'''--loadPlugin'''" option. Use "''--noPlugins''" followed by a list of individual "''--loadPlugin''" options, to tune startup time with a minimum set of required plugins being loaded.

*'''<code>--loadPlugin <pluginName></code>''' Force loading a specific plugin. This is only useful if a "'''--noPlugins'''" option was given before. ''pluginName'' is the name of the folder in the "plugin" folder (under the expecco installation folder). Use "''--noPlugins''" followed by a list of individual "loadPlugin" options, to tune startup time with a minimum set of required plugins being loaded.

*'''<code>--noUpdateCheck</code>''' If configured by the user's settings, expecco automatically checks for updates and patches when started (by checking the exept web-server for the presence of new patch files). This option disables that check, even if configured in the settings. Notice, that this is usually controlled by the user settings; however, in situations where settings are shared among multiple machines (network drive) and a test host has no (or should not have) internet access, it may be useful to disable this from the command line. It is especially useful, if you are disconnected from the Internet (isolated test-lab), to avoid time delays resulting from connection failures.

*'''<code>--requireLogin</code>''' Opens expecco in a (lightweight) multi-user mode, in which a username must be entered before the actual interaction with expecco begins. This user name will be used to load custom per-user settings (named "<code>.expeccoSettings_<name></code>") and will also be used in the generated reports. Also, the "''File''" menu will contain an additional "''Logout''" menu item, which brings back the initial login dialog. This mode is useful, if expecco is used on a machine by multiple users, and expecco should remain opened (i.e. as a test stand). For example in a production floor, where tests are executed in multiple shifts by multiple operators.

*'''<code>--load <fileName or packageName></code>''' Loads a class file, extension or user plugin. The argument must be either the name of a Smalltalk source or binary file, or the name of a package (which must be found in the "<code>packages</code>" subfolder under the expecco installation folder). For details on how to generate such packages, read [[Creating_new_Class_Library_Packages/en | "Creating new Class Library Packages"]].

==== Test Execution ====
*'''<code>--execute <fileName></code>''' read and execute a suite. Starting with expecco 2.10, you can also use "-E <fileName>", which makes the command line a bit shorter.

*'''<code>--execute</code>''' without a filename, this should be the last argument of a scatter-gather dynamically generated suite command (see below: scatter-gather tests)

==== Test Selection ====

the following options allow for individual test plans to be selected for execution from a suite which contains multiple test plans. Without any such option, ''--execute'' will run all top-level testplans found in the suite in sequence.

*'''<code>--testPlanName <namePattern></code>''' Only execute test plans with a matching name. For backward compatibility, "'''<code>--testSuiteName <namePattern></code>'''" is still supported and has the same effect.

*'''<code>--testPlanTag <tagPattern></code>''' Only execute test plans with a matching tag. For backward compatibility, "'''<code>--testSuiteTag <tagPattern></code>'''" is still supported and has the same effect.

*'''<code>--testPlanID <uuid></code>''' Only execute that particular test plan (repeat to execute multiple test plans). Starting with release 2.7, the following shortcut can also be used: '''<code>--testSuiteID "<uuid1>,<uuid2>,...,<uuidN>"</code>'''. For backward compatibility, "'''<code>--testSuiteID <uuid></code>'''" is still supported and has the same effect.

==== Scatter Gather Test Suite Composition ====

these options allow for a test plan to be composed out of a single or multiple of individual suite files. When composing, a new test plan is temporarily created, which contains the specified test cases. This is in contrast to the above options, where preexisting test plans are selected for execution.

Typically, this kind of composition is used when expecco is called from a QA system, such as Polarion or HP Quality Centre, where individual "test sets" are composed out of a collection of existing test cases.

Notice, that this may lead to longer startup times, depending on the number of suites found in the suite directory, because suite files there will be opened and searched for matching test cases. If the same set of tests needs to be executed multiple times, it may be agood idea to use the "--saveSuite" option, to have the composed suite saved into a file for later reuse.

Also notice, that this works best, if testcase have unique names or are known by their ID (which is globally unique). If your test management system can provide unique identifiers, these should be used to name your testcases inside the suite (typically, a unique name of the test-case or requirement is used to name corresponding test-cases).
 (These options are only available in release ≥ 2.7)

*'''<code>--suiteDirectory <dirName></code>''' defines the directory, where test suite files are searched for composed test plans. Test cases as specified in one of the options below must be found in one of the files present there. Notice, that the first file which contains a requested test case action will be chosen. Thus, you should ensure, that only one version of each suite is present there. Typically, an up-to-date test suite directory as checked out from the revision control system is specified here. If this argument is not given, test cases are searched in the list of explicitly listed suite files (".ets" arguments).This option also specifies the directory where suites are found for remote execution (see description of SOAP and REST services below).

*'''<code>--suiteTitle <string></code>''' defines the name of the new test plan, which is created dynamically. This is used to control the labels in the generated report files.

*'''<code>--testCaseNames <name-list></code>''' defines the test cases to be included in the test by name. name-list is a list of comma-separated names of the individual test actions. Please only use this option, if your testcases have unique names and are found only once in any suite found in the suite directory. Otherwise, the first suite which contains that name will be chosen (see below for better selection options).

*'''<code>--testCaseFIDs <id-list></code>''' defines the test cases to be included in the test by function ID. id-list is a list of comma-separated UUIDs of the individual test actions. This option is probably not very user-friendly for a human, but allows for a calling program (or script) that the testcase is found even if it has been renamed in the meanwhile (remember that functional IDs are assigned once when an item is created and remain unchanged over the whole lifetime).

*'''<code>--testCaseIDs <id-list></code>''' defines the test cases to be included in the test by version ID. id-list is a list of comma-separated UUIDs of the individual test actions. This option may be very unfriendly for a human user, but allows for a calling program (or script) to ensure that a particular testcase with a particular version is found and executed, even if the testcase has been renamed or modified in the meantime (remember that the ID is changed with every modification). If the same testcase is found in multiple suite files (i.e. in different versions), this will ensure that the correct version will be executed

*'''<code>--saveSuite <fileName></code>''' saves the generated as-hoq suite. Useful if you want to archive such a dynamically generated scatter-gather suite separately from the result file(s), or to automatically construct new suites. Notice that the ".elf" result file will always include the generated ad-hoq suite, so archival of the generated ad-hoq suite is only needed if you generate pdf, html or other non-elf reports.

==== Test Parameters ====

*'''<code>--parameter <fileName></code>''' / '''<code>-P <fileName></code>''' Load a parameter set from a file. A parameter set contains values for a test suite's top environment. This can be either in XML format, as generated with the [[Environment_Editor|"''Save-Parameter-Set''" menu function]], a CSV file, containing key-value pairs or a JSON file containing a JSON dictionary object.Parameter files in either format can be created manually in a text editor, provided by a QM system (such as expeccoALM, HP Quality Center or similar), generated by another controlling program or generated by expecco itself via the "''Save-Parameter''" menu function of the [[Environment_Editor|environment editor]].The parameter file may contain values for a subset of the environment variables. In this case, the values from the parameter file overwrite corresponding values present in the loaded test suite, leaving other values unchanged.

*'''<code>--parameter:<key>=<value></code>''' / '''<code>-P:<key>=<value></code>''' Sets an individual parameter for the next "--execute" argument.If multiple "--execute" arguments are given (i.e. multiple suites are to be executed in sequence), these parameter values are collected and given to the next execution only, and overwrite corresponding values from either a parameter set (see above) or from the suite itself.Thus, it is possible to execute the same suite with different parameters in one command line (see example above). (this option is available with expecco vsn >= 2.10)

==== Test Execution via Scripting ====
*'''<code>--scriptFile <fileName></code>''' read and execute a script from a file (see scripting below).

==== Reporting ====

*'''<code>--verdicts</code>''' Send execution and result info in human readable format to the stderr output. (see [[#Verdicts Example|example below]].)

*'''<code>--logFile <fileName></code>''' Used to change the name of the generated log file, where stderr is written to. This is only useful if running in server mode.

*'''<code>--exitCode <n></code>''' Defines the exit code to be used independent of the test outcome. The default is 0 (zero) if all tests pass, and non-zero when they do not. However, some calling programs (make/jenkins,...) may misinterpret this exit code and treat the whole job as non-executable. Use this flag to prevent this. It is still possible to change the exitCode for a particular outcome by adding one of the following options after this option.

*'''<code>--exitCodeOnFail <n></code>''' Defines the exit code in case any test ends with a test-failure status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute. This option also changes the exitCodeOnError and exitCodeOnInconclusive values (see below), unless explicitly defined by those options.

*'''<code>--exitCodeOnError <n></code>''' Defines the exit code in case any test ends with a test-error status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute. This option also changes the exitCodeOnInconclusive values (see below), unless explicitly defined by that option.

*'''<code>--exitCodeOnInconclusive <n></code>''' Defines the exit code in case any test ends with an inconclusive status. The default is 0 (zero), so that when you run expecco out of make, jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute.

*'''<code>--elfReportFile <elfFilename></code>''' Writes a report in expecoo's native XML logfile format. The report contains a lot of detail information and could be processed by an XSLT processor or a similar tool. It also contains enough additional information about test plans and actions so that expecco can redisplay the activity log tree from this file. The generated file can be opened directly via the command line ("expecco <file>.elf") or by double clicking on the elf-file in the operating system's desktop.

*'''<code>--csvReportFile <csvFilename></code>''' Writes a summary report in CSV format. Each row consists of: 
** ''TESTSUITE'' - the filename
** ''TESTPLAN'' - the test plan
** ''TESTCASE'' - the test case
** ''VERDICT'' - the test result; one of SUCCESS, FAILED, ERROR or INCONCLUSIVE
** ''INFO'' - additional info in case of failure
:Additional pseudo verdicts such as STARTTIME, ENDTIME etc. are written. A typical CVS output file can be found in the [[#CSV File Example|examples]].

*'''<code>--textReportFile <textFilename></code>''' Writes a summary report in a human readable textual format. A typical text output file can be found in the [[#Textual File Example|examples]].

*'''<code>--xmlReportFile <xmlFilename></code>''' Writes a report in XML format. The report contains a lot of detail information and could usually be processed by an XSLT processor or simular tool. A typical XML output file can be found in the [[#XML File Example|examples]].

*'''<code>--pdfReportFile <pdfFilename></code>''' Writes a summary report in pdf format.

*'''<code>--htmlReportFile <htmlFilename></code>''' Writes a summary report in html format.

*'''<code>--junitReportFile <htmlFilename></code>''' Writes a summary report in a junit compatible XML format. Useful, when expecco is to be started by jenkins or similar driver programs.

*'''<code>--polarionReportFile <htmlFilename></code>''' Writes a summary report in an XML format which is especially suited for the Polarion QM tool. The structure of the generated XML is the same as with the junit format above, but a slightly different time format is used.

*'''<code>--reportTemplateName <name></code>''' Use the given report template (must be an element inside the test suite) for the following "--xxxReportFile" argument. If no such argument is given, the default template as defined in the suite is used.

==== Services ====

*'''<code>--server</code>''' Starts expecco in server mode. This combines the "''--service''", "''--infoService''" and "''--remoteControlService''" flags. All of those services as described below are started with that single command line argument.

*'''<code>--service</code>''' Starts expecco in server mode. In this mode, HTTP-SOAP and HTTP-REST requests can be used to remote-control expecco's execution; especially, to execute and monitor tests, and upload results. The most obvious use for this is for expecco to act as an execution host (test slave) for an expeccoALM or Polarion server. However, because standard protocols are used, this may also be used to interface the execution engine to many other QM management or automation systems (e.g. HP Quality Centre). The interface is described below.

*'''<code>--infoService</code>''' Provide an additional info service which allows for monitoring and control of an expecco server via a web browser (server mode only).

*'''<code>--remoteControlService</code>''' Provide an additional service to interact with a running test. Dialog requests, single stepping, starting, pausing and stopping of tests is possible via remote REST requests. This service is used by the Android remote control app, which is available upon request (server mode only).

*'''<code>--port <portNr></code>''' Used to change the HTTP and SOAP port numbers, when running in server mode. The default is 9090 (server mode only).

*'''<code>--scripting <portNr></code>''' Enable scripting (remote control via Telnet ascii interface) on portNr ([[#Scripting Example|see more below]]).

*'''<code>--allowHost <hostName></code>''' Allow hostName to connect to the scripting port. Repeat for multiple hosts (see more below).

==== Utility Functions ====

*'''<code>--diff <file1> <file2></code>''' Print differences between two test suites. This can be used eg. to automatically generate log messages for a revision control system (please read the section on "Integration with Source Code Management System" below). (This function is only available in release ≥ 2.7)

=== Command Exit Status ===

*0 - all tests passed

*>0 various other errors (command line, file not found, etc.)

*101 - at least one test failed (FAIL status). This exitCode can be overwritten by a command line argument.

*102 - at least one test was inconcusive (INCONCLUSIVE status). This exitCode can be overwritten by a command line argument.

*103 - at least one test lead to an error (ERROR status). This exitCode can be overwritten by a command line argument.
 
The diff option returns 0 if the compared suites are the same, or 200+n, (where n is the number of differences) otherwise.

== Sample Outputs ==

The following output files were generated by executing the test suite from the file:
:"C:\Programme\exept\expecco\testsuites\projects\Example.ets"
which contains a single test plan named:
:"Example Testplan"
which contains three test cases named:
:"Test1"
:"Test2"
:"Test3-Should fail"
of which the first two are supposed to PASS and the last one generates an ERROR.

All timestamp information is written in ISO8601 format.

Be reminded that the following reports are condensed reports, which only contain a subset of the information contained in expecco's native ".elf" file format. The "elf" file contains all of the execution, trace and data-flow information and the original suite as executed. "elf"-files can be reloaded at any time into the expecco UI and the test be reexecuted. Also, any of the other reports can be regenerated, posyibly with different report options (i.e. detail).

Thus it is highly recommended that these "elf" files are archived after a test run, in addition to any of the condensed report files (eg. pdf or junit report).

=== CSV File Example ("<code>--csvReportFile</code>" option) ===

By default, entries are separated by ";"-characters. Additional double quotes (") are used to delimit strings with embedded ";" or spaces. Any double quote within such a string is doubled.
CSV is a simple and very common interchange format.
For example, CSV files can be imported into Microsoft Word, Exel and Openoffice (and many other).

TESTSUITE;TESTPLAN;TESTCASE;VERDICT;INFO
;;;StartTime;2008-10-31T08:57:13.689
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test1;PASSED;
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test2;PASSED;
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";"Test3 - Should fail";ERROR;
;;;EndTime;2008-10-31T08:57:18.746

=== XML File Example ("<code>--xmlReportFile</code>" option) ===

<SummaryReport>
<StartTime>2008-10-31T08:56:49.774</StartTime>
<TestSuite>
<File>C:\Programme\exept\expecco\testsuites\projects\Example.ets</File>
<TestPlan>
<Name>Example Testplan</Name>
<TestCase>
<Name>Test 1</Name>
<Verdict>PASSED</Verdict>
</TestCase>
<TestCase>
<Name>Test 2</Name>
<Verdict>PASSED</Verdict>
</TestCase>
<TestCase>
<Name>Test 3 - Should fail</Name>
<Verdict>ERROR</Verdict>
</TestCase>
</TestPlan>
</TestSuite>
<EndTime>2008-10-31T08:56:55.142</EndTime>
</SummaryReport>

This is not to be confused with the "elf" result file format, which is also XML based, but contains a lot more detail.

Notice also, that the junit report format ("<code>--junitReport</code>" option) is similar in structure but uses different tags.
Junit reports are compatible to reports generated by Java jUnit frameworks.
They can thus be used to generate reports and trends in Jenkins/Hudson and other tools which understand the jUnit report format.

=== Textual File Example ("<code>--textReportFile</code>" option) ===

Test Execution Summary
Start: 2008-10-31 08:56:12.751
TestSuite: "C:\Programme\exept\expecco\testsuites\projects\Example.ets
TestPlan: Example Testplan
Test 1 ....................... PASSED
Test 2 ....................... PASSED
Test 3 - Should fail ......... ERROR
Finish: 2008-10-31 08:56:18.009



=== Verdicts Example ===

the "<code>--verdicts</code>" option generates a simple trace on the standard error (to be redirected into a file):

C:\selftest\commandLineArgs> expecco --noBanner --noTray --verdicts
--parameter paramesForTest.xpar --execute parameterTest.ets 
Expecco [info]: start testSuite "parameterTest.ets"...
Expecco [info]: using parameters "paramesForTest.xpar"...
Expecco [info]: start testPlan "Test Parameters From CommandLine"
Expecco [info]: start testCase "Validate Parameters"
Expecco [info]: done testCase "Validate Parameters"; STATUS=PASSED
Expecco [info]: done testPlan "Test Parameters From CommandLine"; STATUS=PASSED
Expecco [info]: done testSuite "parameterTest.ets"; STATUS=PASSED

== Integration with Quality Managament and Automation Tools ==

=== Integration with Jenkins ===

To have expecco tests being executed automatically by Jenkins, take the following example as a guideline. This is a real world setup, taken from our own setup within eXept.

# Create a test job, which is triggered by a successful build (or a change in the test suite repository)
# Check the "Block Build while prerequisite Jobs are Active" flag
# Check either the "Trigger from Source Code Management" or the "Trigger from other Job" flags
# Check "Abort build if it is Stuck" (just to make sure, that a faulty suite does not block Jenkins)
# Check "Fail the Build if Stuck" and give it a reasonable elastic Time-out Strategy (we use 300% of the last 10 builds, to make sure a longer execution time due to more test cases will not be interpreted as a stuck, and an extra timeout of 30 minutes. The timeout is very generous for the expected execution time of a few minutes).
# Check "Run xvnc during Build" to allow for monitoring, what is going on. This is also required, if the test needs a UI.
# Define the "Build Procedure" as "Execute Shell Script" (Unix/Linux) or "Execute Batch Job" (Windows)
# Enter a build procedure similar to the ours, which is:
#::<code>cd exept\expecco\application
#::del *.junit
#::expecco.com --noBanner --exitOnInternalError --noTray \
#::::--jUnitReportFile selfTestResult.junit \
#::::--execute ..\projects\expecco\eXpeccoSelfTest.ets
#::expecco.com --noBanner --noTray \
#::::--jUnitReportFile CommunicationWithExpeccoNETResult.junit \
#::::--execute ..\projects\expecco\CommunicationWithExpeccoNET.ets</code>
#:The details (especially paths and names) will of cause be different in your setup. The above uses the relative paths as it first changes the current directory to where the previous build has compiled the executable, which will of course not be the case in your setup.
# Define a "Post-build Action"
# Check "Publish Junit Test Results"
# Enter a path expression to declare the location of the resulting reports. Here, we used:<PRE>exept\expecco\application\*.junit</PRE>
# Check the "Publish Test Attachments" flag, so the results will be presented in the Jenkins management console

That's it! Because expecco has been told to generate jUnit compatible report files, we can use Jenkins' existing jUnit support. However, the jUnit xml format does not support the full range of information which is present in the native expecco result files (especially the activity log and pin value information is not included). Therefore, it is a good idea to also generate a regular ".elf" (expecco log file) and add it to the archived build artefacts.

=== Integration with expeccoALM ===
Expecco and ExpeccoALM (formerly called "''expeccoNET''") have been originally designed to work together. Therefore, only a minimum setup is required:
# ensure that an expecco test execution slave is running on each test host (server farm, virtual machines, etc.). Depending on the operating system, this is either done by installing expecco as a service (Windows), or by adding appropriate startup actions to your "init.d" files (Unix).
# define the test host(s) in expeccoALM.
# (optionally) define the devices available and attached to the execution slave machine in expeccoALM

ExpeccoALM will ask the expecco slaves about their operating system environment. So jobs will be automatically executed on matching CPU/OS machines. However, if tests require special resources (devices) to be attached, these must be defined and listed in expeccoALM as well. If your test has corresponding resource-requirements defined (see resources/inventory), expeccoALM will both ensure that the test will execute on the correct machine, and also reserve the resource during the execution. Also, test scheduling, if defined to be automatic, will be optimized to minimize resource usage, and to ensure that a higher number of tests can be executed in parallel.

=== Integration into a SOA Infrastructure ===

For this, expecco should be started on the test host(s) in so called "slave" mode.
In this mode, expecco awaits for execution commands via SOAP or REST, executes tests in the background and returns status information (progress) and results (reports).

Because tests may execute for a long time (hours or even days), the execution is performed asynchonously; first, the test has to be downloaded to the slave, then execution started. The start-command returns a ticket, which is a test-run-identifier, by which the execution progress can be queried (polled) while the test is running. Finally, a "finished" status is returned, upon which the result can be aquired via another service call.

Multiple such test slaves can be started on multiple machines, and each test slave may (if required) execute multiple tests in parallel (although this is usually limited to one, to avoid conflicts when external resources are accessed).

To start expecco in slave mode, use the command line:
expecco --service

or, if the default port (9090) is not available, use:
expecco --service --port 9090

The service interface is described below; typically, you can talk to expecco via:
http://localhost:9090/expeccoService
or:
http://localhost:9090/expeccoService/rest

The SOAP wsdl is returned via:
http://localhost:9090/wsdl/ExpeccoSOAPService.wsdl

and - if the inforService is also running - general status information with:
http://localhost:9090/info

=== Integration with HP Quality Center ===

This is described in the [[ HP Quality Center Plugin ]] document.

=== Integration with Polarion ===

This is described in the [[ Polarion Plugin]] document.

== Integration with Source Code Management Tools ==

=== Background Info on what is Contained in a ".ets" File ===

Expecco stores testsuites in a file with '.ets' extension (which stands for: "''Expecco-Test-Suite''") and result logs in '.elf' files (stands for: "''Expecco-Log-File''").
These are technically zip files - i.e. a bundle of individual files which can be extracted with the common zip command line tool (winzip under Windows systems, zip/unzip under Unix systems).

For example, "<code>unzip -l foo.ets</code>" lists the individual components, of which especially the block descriptions and attachments may be of interest.

Notice, that you have to be careful when ets-files are bundled with zip manually: for various consistency checks, expecco generates a validation signature of the components and saves this as an additional file inside the .ets file.
This signature file must be preserved and it must be consistent with the other zip-components. In effect, this means that an ets can only be constructed from the very same components, using the very same signature file as were extracted before. Otherwise, expecco refuses to load the ".ets" file later.

=== Version Management of ".ets" files ===

Unless a QA system like "expeccoALM" is used, ets-files can be stored and maintained in any other source code management (SCM) system, for example, CVS, SVN, hg/Mercurial, git, Perforce etc.
Make sure to store the .ets as binary file, and/or disable source expansion of version tag lines (for example, "$Header" or "$Id" in CVS). Consult your particular SCM system's documentation on how this is done.

As an alternative, it is possible to unzip the ets into individual components, store them separately, and zip them back into an ets, when a previous version is extracted from the SCM system. However, you must be careful to preserve the contents exactly as is, including the signature and other meta data, and not mix versions. I.e. all individual component files must be checkedIn/out in sync and as a group - it is not possible to update individual files from previous versions. The reason is that action blocks are referred to by their versionID, and these IDs will certainly be inconsistent, when previous versions of individual action blocks are mixed into another version's suite.

If, for whatever reason, you must checkin individual action blocks, we highly recommend to check in BOTH the bundled ets (and use that for later test execution), AND check in the individual components, and use only those for meta actions, such as comparison, documentation or other administrative tasks.

=== Generating Diff Lists or other Version Information ===

Many source code management systems allow for hook-scripts to be added to checkin/checkout actions, and/or to redefine the command to be used for diff-list generation.

For example, in the SVN system, an external diff tool can be defined. You could write a little shell or batch script, which calls expecco with the "<code>--diff</code>" option which is described above. Thus, you would get meaningful diff output even from checked in ets-bundle files.

The "<code>expecco --diff</code>" option is also useful as a command line tool to get diff lists - even if your SCM system does not allow for such automatic hooks.

== Scripting ==

Expecco can be scripted either by reading a script from a file or remote controlled via a telnet like command-line interface.
This is useful to execute complex test scenarios and meta tasks, to create or manipulate test suites automatically and for self-testing expecco by using another expecco to control its GUI.
It can also be used to execute and automate more complex scenarios without using expeccoALM.
 Example uses are:
* Sequentially load and/or execute all suites found in a folder, reimport libraries, save the updated suite
* Construct new suites by merging/selecting tests from other suites
* Bulk renaming, commenting, attributing etc.
* Change attachments inside a number of suites
* Controlling an application or web interface (via a GUI plugin) and saving a sequence of screen shots

By default, the scripting interface expects expressions in JavaScript syntax (but with a Smalltalk object model),
similar to the language used for elementary block definition. However, the language can be changed to Smalltalk syntax via a "~" directive.

=== Script File Example ===

To control expecco via a scriptfile, use the "<code>--scriptFile <filename></code>" command line argument, where <filename> must be a file containing JavaScript expressions.

For example, the following script file named "run3Suites.js" may contain the code:
<PRE>
// Example for an automatic expecco script.
// (loads and executes a number of test suites)
//

// to enable debugging in case of an error.
// STXScriptingServer.errorDebugging(true);

var files = [
"foo.ets",
"bar.ets",
"baz.ets",
];

Expecco::ExpeccoPreferences.current.automaticReimportOnLoad(true);
Expecco::ExpeccoPreferences.current.checkForReimportableImportsOnLoad(true);
Expecco::ExpeccoPreferences.current.checkForAnchestorOnAutomaticReimport(false);
// Expecco::ExpeccoPreferences.current.libraryPath(importPathes);

// --------------------

function executeTestPlan ( aTestPlan ) {
Stderr.nextPutLine("executing testplan "+aTestPlan.name()+"...");
resultList = aTestPlan.execute();
Stderr.nextPutLine("done.");
}

function runSuite(suiteFile) {
var loadedProject;

Stderr.nextPutLine("loading "+suiteFile+"...");
expecco.loadProjectFromFile(suiteFile);
loadedProject = expecco.project();

if (loadedProject == null) {
Stderr.nextPutLine("failed to load library "+suiteFile+".");
Smalltalk.exit(1);
} else {
loadedProject.allTestPlansDo( executTestPlan );
}
};

files.do(runSuite);
</PRE>

And can be executed with:

expecco --scriptFile run3Suites.js

for windowless operation, use the "<code>--noWindow</code>" command line argument.
To speed up the startup, you can turn off the loading of plugins, with a "<code>--noPlugins</code>" argument (and possibly load any required plugins explicitly via additional plugin arguments).
Finally, enable debug messages with a "<code>--debug</code>" argument.
Thus, the recommended options for scripting are:

expecco --debug --noPlugins --noWindow --scriptFile run3Suites.js

of course, this command line can be put into a shell (or batch) script file, and then executed with a single word command.

=== Telnet Scripting Example ===

The remote scripting service is enabled when a "<code>--scripting</code>" command line argument is given.
By default, the service only accepts connections from the local host (for security reasons). Using the "<code>--allowHost</code>" option, more hosts can be gained access to the scripting feature - but be aware, that this opens a potential security hole, as all of the internal functions can be accessed via the scripting system (and this includes the possibility to write files and call operating system services with the access rights of the one who started the scripting server).

When used with a remote script connection (telnet),
additional connection- and execution related commands are introduced by lines starting with the "~" (tilde) escape character (similar to telnet).
For example, "~." (tilde-period) is used to close the connection.
Press "~?" (tilde-question) for help.

The following is a trace of a typical scripting session (user input in bold):

c:\programs\expecco> expecco --scripting 8008
c:\programs\expecco> ... expecco now running in the background with GUI ...
...
c:\programs\expecco> telnet localhost 8008
Welcome to Expecco (Type ~? for help)
> println(expecco);
an Expecco::Browser
> expecco.menuNewProject();
...expecco performs the new-function from its menu...
> expecco.loadProjectFromFile("C:\Users\cg\testsuites\webedition\projects\BearerTest.ets");
...expecco loads the testSuite...
> expecco.close();
> ~.
Lost Connection.
c:\programs\expecco>

You can also start a scripting session without an initial expecco browser window:

c:\programs\expecco> expecco --noWindow --scripting 8008
c:\programs\expecco> ... expecco now running in the background without GUI ...
...
c:\programs\expecco> telnet localhost 8008
Welcome to Expecco (Type ~? for help)
> println(expecco);
an Expecco::Browser
> expecco;
> ~v+ // turn result-printing on
> expecco
an Expecco::Browser
> ~v- // and off again
> expecco.loadProjectFromFile("~/SomeTest.ets");
...expecco loads the testSuite...
> var blk = expecco.project.elementWithName("My Action");
> blk.name("My Fun Action");
> expecco.saveProjectToFile("~/ModifiedTest.ets");
> expecco.close();
>~.
Lost Connection.
c:\programs\expecco>

== Scripting API Overview ==

A few objects are predefined by name; among them are "''expecco''", which refers to the browser itself (i.e. the UI) and "''environment''", which refers to a collection of variable bindings (this is a dictionary of interpreter variables - not to be confused with a variable environment as known inside an expecco activity block).
 New variables can be defined with a "<code>var <name>;</code>" statement. For example:
<CODE><PRE>
var ws;

ws = new ExpeccoWorkspaceApplication;
ws.open();
ws.close();
</PRE></CODE>

==== expecco Object ====

The variable named "''expecco''" refers to the opened GUI-object, which represents the expecco application itself.

===== Expecco Functions =====

*'''project()''' the current project
*'''currentApplication()''' the current page (initially, there is only one)
*'''currentTreeApplication()''' the current tree sub-application

*'''selectModelItem( anItem )''' select an item and open an editor for it
*'''selectedModelItems()''' returns a collection of selected items
 

===== Menu Functions =====
These execute the underlying menu functions (as if clicked by the user).

*'''menuNewProject()''' creates a new testSuite
*'''menuOpen()''' opens a dialog requesting a testSuite
*'''menuExit()''' closes the expecco application

*'''loadProjectFromFile(fileNameString)''' load a testSuite
*'''saveProjectToFile(fileNameString)''' save the testSuite
*'''selectTestPlanWithName(testPlaneNameString)''' select a testplan item by name
*'''selectTestPlanWithFunctionalId(uuid)''' select a testplan item by uuid

*'''testSuite()''' retrieves the testSuite object (see below)
 

===== Test Suite (Project) Functions =====
the project as returned by the above "project()" function provides access to its elements:
 (see also [[ Expecco API#Test Suite Project Functions]])

*'''authorName()''' get the author name string
*'''authorName(aString)''' set the author name string
*'''versionString()''' get the version string
*'''versionString(aString)''' set the version string
*'''projectsWorkingDirectory()''' the directory, where attachments etc. are found
*'''ensureEnvironment()''' an instantiated environment (concrete values). See below.
*'''elementWithName( nameString )''' returns a matching element or null if not found
*'''elementWithId( aUUID )''' returns that element or null if not present. (create the UUID with "<stringConstant>.asUUID" )
*'''elementWithFunctionalId( aUUID )''' returns that element or null if not present
 

==== Environment Object ====

Environment objects are used to store key-value bindings for expecco variables. Environments form a hierarchy, where values are searched for in an environment's parent environment, if not present. This hierarchy follows the containing compound activity chain up to the project (= test suite) environment.
Additional temporary environments are kept by the executor and the browser, to keep temporary values for a single execution's or a single session's lifetime.

*'''at(key)''' retrieves a value, given the name of the entry. Raises and error if no variable exists by that name.
*'''at_ifAbsent(key, default)''' like above, but returns default if no variable exists by that name (instead of raising an error).
*'''includesKey(key)''' true if a variable by that name exists, false otherwise.
*'''at_put(key, value)''' store value as variable named key. Raises an error, in an attempt to change a readOnly variable
*'''environmentDescription()''' returns the environment's description. This describes types, default values and read/write attributes per entry.
 

==== EnvironmentDescription Object ====

This is a collection of entries which describe variables of an environment. It does only hold the description, not the bindings themself; i.e. it contains the information required to instantiate an environment. EnvironmentDescriptions inherit from OrderedCollection and therefore entries are accessed via "at:" using a numeric index from 1 to the environmentDescription's size.

Entries (as per variable) provide the following protocol:

*'''name()''' the name of the variable
*'''isReadOnly()''' true if readonly
*'''defaultValue()''' the initial value, assigned when the environment is created
*'''datatype()''' the type of the variable
*'''comment()''' description
 

== Remote Controlling and Monitoring Expecco ==

Expecco itself can be automated by various mechanisms:

* via command line arguments (described in [[ #Command Line | "Command Line"]] above)

* via script files (see [[ #Script File Example | "Script File Example"]] above)

* via the telnet interface (see [[ #Telnet Scripting Example | "Telnet Scripting Example"]] above)

* via standard RPC mechanisms, such as SOAP or REST.

Especially the RPC mechanisms are useful to integrate expecco into the company test infrastructure.
Such interfaces are meant for programmatic control of an expecco slave from quality management, application life cycle and other scheduling tools.
Our own companion product, ExpeccoALM and third party tools, such as Polarion use these service interfaces.

Notice, that for integration into a Jenkins infrastructure, command line arguments or scripts may be a more cost efective means to control automated expecco testruns.

=== Expecco as a Slave Node in a Test Lab ===

The service interfaces are useful to control unmonitored slave machines in the network, among which expecco test execution jobs are scheduled by another program. ExpeccoALM and other quality management tools use these to initiate test runs in a test server farm.
For this, the basic operations "download of a suite", "execute a suite" and "requesting execution results" are available as service calls.

Both SOAP and REST services are available, if expecco is started with the "''--server''" argument.
An optional "''--port''" argument allows for the HTTP port to be changed from the default (9090) on which expecco is listening.

For debugging and testing, the service can be also be started from the interactive UI, via expecco's main menu (in the "''Extras''" - "''Web-Services''" - "''Start / Stop''" menu items).

These services use HTTP requests as transport layer.

==== Expecco SOAP Service Interface ====

This accepts SOAP requests, via the URL "<code>/expeccoService</code>". I.e. the default URL is "<code>host:9090/expeccoService</code>".
A partial WSDL spec can be aqcuired from the running service via "<code>host:9090/wsdl/ExpeccoSOAPService.wsdl</code>" (partial, because it is currently not does not contain complete type information).

The service entries are:

===== Loading and Executing a Suite =====

The execute request is the main service entry. It passes the suite and also optional parameters.

The test suite can be bade available to expecco either by passing it with the request (as base64 CDATA), or by passing a URL from which expecco can fetch the suite iteslf.

The execute call contains the following fields:

<message name="expecco_executeProject_v5_Request">
<part name="id" type="UUID"/>
<part name="testSuiteId" type="UUID"/>
<part name="dataSource" type="xsd:string"/>
<part name="dataSourceUri" type="xsd:string"/>
<part name="environment" type="xsd:arrayType"/>
<part name="testplans" type="xsd:arrayType"/>
<part name="resources" type="xsd:arrayType"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

and responds with:

<message name="expecco_executeProject_v5_Response">
<part name="result" type="xsd:string"/>
</message>

This call starts execution, and immediately returns a response, which consists of an identifier.
This identifier can later be used to ask expecco about the execution status. As a test may take a long time to finish,
it is useful to poll via status requests from time to time, to see if the execution has finished and to get progress status.

The parameters are:

* id - mandatory; a ticket ID; this should be a UUID-string, to avoid possible conflicts
* testSuiteId - mandatory; the UUID of the suite to execute. See below for details about download optimizations
* dataSource - optional; if present, this should contain the whole ets-file's contents as a Base64 encoded CDATA string
* dataSourceUri - optional; if present, this should be the URI from which expecco shall fetch the suite. See below for details
* environment - optional; top-level environment variable values. This can be used to provide alternative initial values for variables in the top level variable environment (the "Project-Environment")
* testplans - optional; a list of UUIDs of testplans to execute. If not present, all top-level testplans are executed
* resources - optional; a list of resources to be used by the test (see expeccoALM resource description)
* optionalParameters - optional; an array containing additional parameters as key-value elements.

The "optionalParameters" field:

A list of key-value elements (i.e. must have an even number of elements, of the form [k1 v1 k2 v2 ... kN vN] ).
Each key is an xsd:string, each value's type depends on the key, but all of them are currently also strings.
The list of supported parameters is open for future extension of the interface. Currently, the following are recognized:
* [ "generateLog" xsd:boolean ] - the boolean arg must be "true" or "false"
* [ "generatePDFReport" xsd:boolean ] - boolean arg, must be either "true" or "false"

The "testplans" field:

this allows selective execution of individual test plans and also individual test cases (from within a test plan) from the suite.
If not present, all test plans as present in the suite are executed.
If present, the testPlans parameter must be an xsdarray of pairs (i.e. each array element is again an xsdarray with 2 elements).
Each top level element describes one testplan to be executed. The first element of each being the testplan's UUID, the second another array, listing the testcases by UUID.
For example, if the suite contains three testplans, named "a", "b" and "c", with plan "a" having id-a and "b" having id-b as UUID.
A testPlans argument might look like:
<pre>
[
[ id-a ]
[ id-b [ id-tcb-1 id-tcb-2 ] ]
]
</pre>
and specify that testplan "a" should be executed fully (i.e. all test cases), and only the testcases tcb-1 and tcb-2 are to be executed from testplan "b".

The "environment" field:

-- to be described --

The "resources" field:

-- to be described --

The reply consists of the ticket-id, which has to be passed in further status requests.

===== Loading Only =====

It is also possible, to download a suite without execution, via the "download" request:

<message name="expecco_downloadProject_Request">
<part name="testSuiteId" type="xsd:string"/>
<part name="dataSourceBase64" type="xsd:string"/>
<part name="dataSourceUri" type="xsd:string"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

<message name="expecco_downloadProject_Response">
<part name="result" type="xsd:string"/>
</message>

===== Download Optimization =====

Expecco remembers downloaded suites in a temporary folder, to avoid repeated transfers of possibly huge test suites.
If a URI is passed (but no base64 encoded data), expecco checks if the suite is already present on the test host,
and will not fetch it again, if already present. If not present, expecco will fetch the suite via a HTTP request from the URI.

If no URI is passed (i.e. both data and dataURI fields are empty), expecco will either respond with an error reply, if not present,
or with an ok response, if already present.

Thus, if you have to pass the suite as data (i.e. there is no file service available, from which expecco could fetch the suite),
it is recommended to first check if a suite is already present (by sending a download request without data) and check for an error return. If no error is reported, the suite is already there and no further download action is required. If there is an error response,
the client should send the suite with another download request, this time with a non-empty data field.

After any successfull download (either via download, or via execute request), the suite can be executed by an execute request without data.

===== Execution by Suite File Name =====

An alternative to downloading suites is to execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.
The executeTestSuiteFile-request is used to execute one of the suites in that directory.

The call contains the following fields:

<message name="expecco_executeTestSuiteFile_Request">
<part name="id" type="UUID"/>
<part name="fileName" type="xsd:string"/>
<part name="environment" type="xsd:arrayType"/>
<part name="testplans" type="xsd:arrayType"/>
<part name="resources" type="xsd:arrayType"/>
<part name="optionalParameters" type="xsd:arrayType"/>
</message>

If successful, a ticketID is returned (same as above execute-request).

===== Status Request =====

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the above execute request.

<message name="expecco_getExecutionInfo_Request">
<part name="ticketId" type="UUID"/>
</message>

<message name="expecco_getExecutionInfo_Response">
<part name="result" type="xsd:string"/>
</message>

A client may have to send multiple "getExecutionInfo" requests, until a "finished" status is returned.
Expecco will keep the generated reports and log files in a temporary folder, until fetched via a getResult request.
This allows for both expecco and the client to be turned off and restarted, without loosing any status information.

===== Result Request =====

Once finished, reports and log files should be fetched from expecco.

<message name="expecco_getResult_Request">
<part name="ticketId" type="UUID"/>
<part name="removeResultBoolean" type="xsd:string"/>
</message>

<message name="expecco_getResult_Response">
<part name="result" type="xsd:string"/>
</message>

After the "getResult" request, corrsponding files are automatically removed from the temporary folder by expecco.

===== Terminate/Abort Request =====

Use this, to abort and terminate an ongoing test execution.

<message name="expecco_killExecution_Request">
<part name="ticketId" type="xsd:string"/>
</message>

<message name="expecco_killExecution_Response">
<part name="result" type="xsd:string"/>
</message>

===== Remove Ticket Request =====

Use this, to tell expecco, that no further interest exists in a ticket.
If the test is still running, it is aborted. If it is about to be started, it will not be.
Any temporary files which might have already been created due to this execution are removed.

<message name="expecco_killExecution_Request">
<part name="ticketId" type="UUID"/>
</message>

<message name="expecco_killExecution_Response">
<part name="result" type="xsd:string"/>
</message>

===== Ping =====

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

<message name="ping_Request">
</message>

<message name="ping_Response">
<part name="result" type="xsd:array"/>
</message>

===== Cleanup of Old Result/Log Files =====

This request can be used to remove all temporary files, especially leftover report- and log files.
This should be used, if a client has crashed, and lost track of

<message name="expecco_cleanupTempFiles_Request">
</message>

<message name="expecco_cleanupTempFiles_Response">
<part name="result" type="xsd:string"/>
</message>

===== Example Wire Protocol Trace =====

Client asks expecco to execute a suite.

<-- HTTP Request to Expecco --
<PRE>

POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 8925
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">

<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_executeProject_v5 xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<optionalParameters xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[6]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">generateReport</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">generateLog</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">runAllTestcasesIfEmptyTestcaseList</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
</optionalParameters>

<testSuiteId xsi:type="UUID">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<testplans
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:arrayType[1]">
<item
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
enc:arrayType="xsd:anyType[2]">
<item
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xsi:type="xsd:string">f71c4700-7477-11df-a41b-00ff7b08316c
</item>
<item
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
enc:arrayType="xsd:anyType[0]">
</item>
</item>
</testplans>
<id xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</id>
<dataSource xsi:null="1"/>
<dataSourceUri xsi:type="xsd:string">http://127.0.0.1:8662/expeccoALM/tentativeObjects/a84b2d96-d133-47db-9fc2-17208b490bfe.a
</dataSourceUri>
<environment
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[22]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Host__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">sr-laptop</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_LoginUserName__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">admin</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_FullUserName__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">. *admin*</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_TestHost__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">127.0.0.1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_UUID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">e5c9cb30-a253-11e4-9f24-c48508c91d3c</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_ID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">d4</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_Name__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Test For Resources and Skills</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_Summary__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string"></item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Run_UUID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">200d93e1-a258-11e4-b9eb-c48508c91d3c</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Run_ID__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">r14</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_TestSuite_VersionNumber__</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">1</item>
</environment>

<resources
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
enc:arrayType="xsd:anyType[28]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute1-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute2-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute2-2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Float</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0.0</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 2 eeee</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource 2</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute1-1</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
</resources>
</m:expecco_executeProject_v5>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco

<PRE>

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 649
Connection: Keep-Alive

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_executeProject_v5Response xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</result>
</m:expecco_executeProject_v5Response>
</env:Body>
</env:Envelope>

</PRE>

Client asks expecco for execution state

<-- HTTP Request to expecco

<PRE>

POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 635
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfo xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<ticketId xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</ticketId>
</m:expecco_getExecutionInfo>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco (while still executing)

<PRE>

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 2579
Connection: Keep-Alive

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfoResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result>
<executionResultState xsi:type="xsd:string">executingTestSuite</executionResultState>
<currentActivity xsi:type="xsd:string">executing Neuer Testplan</currentActivity>
<pdfReportFileURL xsi:null="1"/>
<summaryResult>
<summaryTestplanExecutionResults xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<summaryTestPlanItems xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<detailString xsi:null="1"/>
<resultActivityState xsi:type="xsd:string">Successful</resultActivityState>
<testplanItemName xsi:type="xsd:string">Neue Aktion</testplanItemName>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanItemExecutionResult</expeccoClass>
</item>
</summaryTestPlanItems>
<testPlanId xsi:type="xsd:string">22623ef0-757d-11df-a41b-00ff7b08316c</testPlanId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanExecutionResult</expeccoClass>
<testPlanName xsi:null="1"/>
</item>
</summaryTestplanExecutionResults>
<testSuiteName xsi:type="xsd:string">Test For Resources and Skills</testSuiteName>
<testSuiteId xsi:type="xsd:string">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestSuiteExecutionResult</expeccoClass>
</summaryResult>
<logFileURL xsi:null="1"/>
<expeccoClass xsi:type="xsd:string">Expecco::SoapExecutionResult::SummaryEncoding</expeccoClass>
<executionProgress xsi:type="xsd:integer">0</executionProgress>
</result>
</m:expecco_getExecutionInfoResponse>
</env:Body>
</env:Envelope>

</PRE>

>-- response from Expecco (after execution)

<PRE>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 2781
Connection: Keep-Alive

.....................
<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_getExecutionInfoResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result>
<executionResultState xsi:type="xsd:string">finished</executionResultState>
<currentActivity xsi:type="xsd:string">executing Neuer Testplan</currentActivity>
<pdfReportFileURL xsi:type="xsd:string">http://127.0.0.1:9090/expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.pdf</pdfReportFileURL>
<summaryResult>
<summaryTestplanExecutionResults xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<summaryTestPlanItems xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
<item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<detailString xsi:null="1"/>
<resultActivityState xsi:type="xsd:string">Successful</resultActivityState>
<testplanItemName xsi:type="xsd:string">Neue Aktion</testplanItemName>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanItemExecutionResult</expeccoClass>
</item>
</summaryTestPlanItems>
<testPlanId xsi:type="xsd:string">22623ef0-757d-11df-a41b-00ff7b08316c</testPlanId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanExecutionResult</expeccoClass>
<testPlanName xsi:null="1"/>
</item>
</summaryTestplanExecutionResults>
<testSuiteName xsi:type="xsd:string">Test For Resources and Skills</testSuiteName>
<testSuiteId xsi:type="xsd:string">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
<expeccoClass xsi:type="xsd:string">Expecco::SummaryTestSuiteExecutionResult</expeccoClass>
</summaryResult>
<logFileURL xsi:type="xsd:string">http://127.0.0.1:9090/expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.elf</logFileURL>
<expeccoClass xsi:type="xsd:string">Expecco::SoapExecutionResult::SummaryEncoding</expeccoClass>
<executionProgress xsi:type="xsd:integer">100</executionProgress>
</result>
</m:expecco_getExecutionInfoResponse>
</env:Body>
</env:Envelope>

</PRE>

Client fetches the report and log files from expecco:

<-- HTTP Request to expecco (fetch logfile)

<PRE>
GET /expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.elf HTTP/1.1
Connection: Keep-Alive
User-Agent: Mozilla/3.0N
Host: 127.0.0.1:9090
Accept-Encoding: chunked
Accept-Language: en,*
Accept-Charset: iso-8859-1,*,utf-8
Accept: */*
</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: application/x-expecco-logfile
Content-Length: 12690
Connection: Keep-Alive
Cache-Control: max-age=86400
Last-modified: Thu, 22 Jan 2015 17:32:50 GMT

... a lot of elf-file data ...
</PRE>

<-- HTTP Request to expecco (fetch pdf report)

<PRE>
GET /expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.pdf HTTP/1.1
Connection: Keep-Alive
User-Agent: Mozilla/3.0N
Host: 127.0.0.1:9090
Accept-Encoding: chunked
Accept-Language: en,*
Accept-Charset: iso-8859-1,*,utf-8
Accept: */*
</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 29768
Connection: Keep-Alive
Cache-Control: max-age=86400
Last-modified: Thu, 22 Jan 2015 17:32:51 GMT

... a lot of pdf data ...
</PRE>

Client releases ticket (so expecco can remove the temporary data)

<-- HTTP Request to expecco

<PRE>
POST / HTTP/1.1
Connection: Keep-Alive
User-Agent: Smalltalk/X 6.2.5.0
Host: 127.0.0.1:9090
Content-Length: 627
Content-Type: text/xml; charset="utf-8"
SOAPAction: ""

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_removeTicket xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<ticketId xsi:type="UUID">ad8011e1-a25c-11e4-b9eb-c48508c91d3c</ticketId>
</m:expecco_removeTicket>
</env:Body>
</env:Envelope>

</PRE>

>-- HTTP response from expecco

<PRE>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 614
Connection: Keep-Alive

.....................
<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
<m:expecco_removeTicketResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
<result xsi:type="xsd:boolean">true</result>
</m:expecco_removeTicketResponse>
</env:Body>
</env:Envelope>

</PRE>
===== Example Session Using "<code>wget</code>" =====

Using "wget" with SOAP is possible, but a little complicated, because correct SOAP requests have to be constructed, and ticket-numbers be extracted from responses. It is much easier with the REST service.

See below for a description.

==== Expecco REST Service Interface ====

This accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

The REST service supports the same set of operations as the SOAP service described above, but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are all HTTP-GET requests, possibly with attached JSON encoded argument data.
The operation is determined by the URI: the last component is the operation name to be executed.

See details [[Starting_expecco_via_Comand_Line/rest/en | "expecco rest service interface"]].

===== ProtocolInfo Request "/expeccoService/rest/protocolInfo" =====

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE"; currently always "GET"
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

{
"URLPath" : "expeccoService/rest" ,
"Service" : "ExpeccoRestService",
"Version" : 1 ,
"Protocol" :
[
{
"Name" : "execute" ,
"Request" : "GET" ,
"Argument" : "(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "start execution; return ticketID." ,
},
{
"Name" : "download" ,
"Request" : "GET" ,
"Argument" : "(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "start execution; return ticketID." ,
},
{
"Name" : "executeTestSuiteFile" ,
"Request" : "GET" ,
"Argument" : "(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "execute suite file; return ticketID." ,
},
{
"Name" : "getExecutionInfo" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Return" : "Dictionary"
"Comment" : "get execution status of an execute job; argument is ticketID." ,
},
{
"Name" : "killExecution" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Comment" : "kill execution of an execute job; argument is ticketID."
},
{
"Name" : "removeTicket" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Comment" : "give up execution of an execute job; if required, kill the job. argument is ticketID."
},
{
"Name" : "cleanupTempFiles" ,
"Request" : "GET" ,
"Comment" : "remove leftover temporary files."
},
{
"Name" : "ping" ,
"Request" : "GET" ,
"Comment" : "test reachability and return some status info." ,
"Return" : "Dictionary"
},
{
"Name" : "protocolInfo" ,
"Request" : "GET",
"Return" : "Dictionary"
}

]
}

===== Execute Request "/expeccoService/rest/execute" =====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

===== Download Request "/expeccoService/rest/download" =====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.

===== Execute File Request "/expeccoService/rest/executeTestSuiteFile" =====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

The file must be present/reachable by the expecco slave.
It may be either an absolute pathname (typically on a shared network drive) or
a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

===== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" =====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

===== KillExecution Request "/expeccoService/rest/killExecution" =====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

===== RemoveTicket Request "/expeccoService/rest/removeTicket" =====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

===== Cleanup Request "/expeccoService/rest/cleanupTempFiles" =====

No argument. no return value.

===== Ping Request "/expeccoService/rest/ping" =====

No argument. Returns an object containing status information.

 

===== Example Wire Protocol Trace =====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>

===== Example Session Using "<code>wget</code>" =====

Using "wget" with SOAP is possible, but a little complicated, because correct SOAP requests have to be constructed, and ticket-numbers be extracted from responses. It is much easier with the REST service.

Assuming, you have a folder containing 3 suites "suiteA.ets", "suiteB.ets" and "suiteC.ets", and you want to send them to a running expecco slave via REST, here is how to do it:

1) to check if the expecco slave is up and running, send it a

=== Expecco Remote Control REST Service Interface ===

A secondary REST service is available to interact with a running test.
This service is used by the "expecco remote control App", which is available for Android devices (tablets and cell phones).

This accepts REST requests, via the URL "/remote". I.e. the default URL is "host:9090/remote".
A description of the supported REST calls can be aqcuired from the running service via "host:9090/remote/protocolInfo".

When this service is active, the standard Dialog requests (input boxes, with "OK"/"Cancel" buttons) will also be presented on the remote controlling app, and can be answered either on the PC-screen OR on a remote android device.
An obvious application of this is when the test system (hardware) needs manual interaction and you have to leave the workplace for this. Here, it is very convenient to be able to answer questions like "Insert Cable X and press OK to proceed" from a mobile device. Avoiding the need to walk back to the workplace to click on the "OK" button.

=== Expecco Short Status Information Service ===

This is a very simple HTTP service, which delivers a single page with a status overview.
This service is started when the "<code>--infoService</code>" or "<code>--server</code>" command line arguments are present.

This accepts HTTP requests, via the URL "/info".
I.e. the default URL is "<code>host:9090/info</code>".

The main use of this service is to quickly check the status of a testslave from a remote webbrowser,
without a need for a more complicated SOAP or REST service client.

Back to [[Online_Documentation#Topic:_Execution | Online Documentation]]

Starting expecco via Command Line/rest/en

2017-04-02T12:36:36Z

Ab:

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the expecco 2.11 implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Array, TestPlanIDs:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Array, TestPlanIDs:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Array, TestPlanNames:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"expeccoExit",
"Request":"GET",
"Comment":"Exit the expecco application."
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"PUT",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"PUT",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job/ticket id
* SuiteFileName - mandatory; name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

ID: 
The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ID have to be passed as JSON String.

SuiteFileName: 
The testsuite file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument. The SuiteFileName have to be passed as JSON String.

Environment: 
The suite environment can be setup/modified with this argument. The environment have to be passed as JSON Array with a list of environment key value pairs. First value of a pair is the environment key second the value.

TestPlans: 
A JSON Array with a list of testplan names. The testplans will be executed in the order defined in the array. If no testplan is given, all testplans included in the suite will be executed.

Resources: 
Within this argument you can pass resource descriptions for the execution.

Parameters: 
If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

JSON Argument Example:

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
"InfoString" "This is an example"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Execution Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing or finished execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Wait for test execution finished Request ====

"host:9090/expeccoService/rest/waitForExecutionResult"

This request wait until the execution with the given job/ticket id is finished. After that it returns the same information as the request getExecutionInfo. With this request no polling on client side is necessary. On the other hand if the client poll the execution state with getExecutionInfo it is possible to fetch information about the progress of the execution from the response.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Get List of available Testsuites Request ====

"host:9090/expeccoService/rest/getListOfTestSuiteFiles"

This query returns a list of available Testsuites for execution. The suites will be searched in the directory passed at startup with the --suiteDirectory argument.

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request ====

"host:9090/expeccoService/rest/download"

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.

The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

==== Exit expecco Request ====

"host:9090/expeccoService/rest/expeccoExit"

Send back a response and exit expecco.

No argument, no return

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>

==== Perl Client ====
This is a small perl example. It starts a test execution on the expecco server and wait until execution is finished. In case of successful HTPP Response (200) the result is printed.

<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-04-01T16:53:42Z

Ab:

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Array, TestPlanIDs:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Array, TestPlanIDs:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Array, TestPlanNames:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"expeccoExit",
"Request":"GET",
"Comment":"Exit the expecco application."
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"PUT",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"PUT",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job/ticket id
* SuiteFileName - mandatory; name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

ID: 
The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ID have to be passed as JSON String.

SuiteFileName: 
The testsuite file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument. The SuiteFileName have to be passed as JSON String.

Environment: 
The suite environment can be setup/modified with this argument. The environment have to be passed as JSON Array with a list of environment key value pairs. First value of a pair is the environment key second the value.

TestPlans: 
A JSON Array with a list of testplan names. The testplans will be executed in the order defined in the array. If no testplan is given, all testplans included in the suite will be executed.

Resources: 
Within this argument you can pass resource descriptions for the execution.

Parameters: 
If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

JSON Argument Example:

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
"InfoString" "This is an example"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Execution Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing or finished execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Wait for test execution finished Request ====

"host:9090/expeccoService/rest/waitForExecutionResult"

This request wait until the execution with the given job/ticket id is finished. After that it returns the same information as the request getExecutionInfo. With this request no polling on client side is necessary. On the other hand if the client poll the execution state with getExecutionInfo it is possible to fetch information about the progress of the execution from the response.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Get List of available Testsuites Request ====

"host:9090/expeccoService/rest/getListOfTestSuiteFiles"

This query returns a list of available Testsuites for execution. The suites will be searched in the directory passed at startup with the --suiteDirectory argument.

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request ====

"host:9090/expeccoService/rest/download"

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.

The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

==== Exit expecco Request ====

"host:9090/expeccoService/rest/expeccoExit"

Send back a response and exit expecco.

No argument, no return

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>

==== Perl Client ====
This is a small perl example. It starts a test execution on the expecco server and wait until execution is finished. In case of successful HTPP Response (200) the result is printed.

<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-04-01T16:52:40Z

Ab:

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Array, TestPlanIDs:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Array, TestPlanIDs:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Array, TestPlanNames:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"expeccoExit",
"Request":"GET",
"Comment":"Exit the expecco application."
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"PUT",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"PUT",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job/ticket id
* SuiteFileName - mandatory; name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

ID: 
The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ID have to be passed as JSON String.

SuiteFileName: 
The testsuite file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument. The SuiteFileName have to be passed as JSON String.

Environment: 
The suite environment can be setup/modified with this argument. The environment have to be passed as JSON Array with a list of environment key value pairs. First value of a pair is the environment key second the value.

TestPlans: 
A JSON Array with a list of testplan names. The testplans will be executed in the order defined in the array. If no testplan is given, all testplans included in the suite will be executed.

Resources: 
Within this argument you can pass resource descriptions for the execution.

Parameters: 
If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

JSON Argument Example:

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
"InfoString" "This is an example"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Execution Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing or finished execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Wait for test execution finished Request ====

"host:9090/expeccoService/rest/waitForExecutionResult"

This request wait until the execution with the given job/ticket id is finished. After that it returns the same information as the request getExecutionInfo. With this request no polling on client side is necessary. On the other hand if the client poll the execution state with getExecutionInfo it is possible to fetch information about the progress of the execution from the response.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Get List of available Testsuites Request ====

"host:9090/expeccoService/rest/getListOfTestSuiteFiles"

This query returns a list of available Testsuites for execution. The suites will be searched in the directory passed at startup with the --suiteDirectory argument.

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request ====

"host:9090/expeccoService/rest/download"

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.

The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

==== expecco exit Request ====

"host:9090/expeccoService/rest/expeccoExit"

Send back a response and exit expecco.

No argument, no return

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>

==== Perl Client ====
This is a small perl example. It starts a test execution on the expecco server and wait until execution is finished. In case of successful HTPP Response (200) the result is printed.

<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T08:36:36Z

Ab: /* Status Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job/ticket id
* SuiteFileName - mandatory; name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

ID: 
The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ID have to be passed as JSON String.

SuiteFileName: 
The testsuite file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument. The SuiteFileName have to be passed as JSON String.

Environment: 
The suite environment can be setup/modified with this argument. The environment have to be passed as JSON Array with a list of environment key value pairs. First value of a pair is the environment key second the value.

TestPlans: 
A JSON Array with a list of testplan names. The testplans will be executed in the order defined in the array. If no testplan is given, all testplans included in the suite will be executed.

Resources: 
Within this argument you can pass resource descriptions for the execution.

Parameters: 
If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

JSON Argument Example:

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
"InfoString" "This is an example"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Execution Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing or finished execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Wait for test execution finished Request ====

"host:9090/expeccoService/rest/waitForExecutionResult"

This request wait until the execution with the given job/ticket id is finished. After that it returns the same information as the request getExecutionInfo. With this request no polling on client side is necessary. On the other hand if the client poll the execution state with getExecutionInfo it is possible to fetch information about the progress of the execution from the response.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Get List of available Testsuites Request ====

"host:9090/expeccoService/rest/getListOfTestSuiteFiles"

This query returns a list of available Testsuites for execution. The suites will be searched in the directory passed at startup with the --suiteDirectory argument.

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request ====

"host:9090/expeccoService/rest/download"

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.

The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>

==== Perl Client ====
This is a small perl example. It starts a test execution on the expecco server and wait until execution is finished. In case of successful HTPP Response (200) the result is printed.

<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T08:36:11Z

Ab:

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job/ticket id
* SuiteFileName - mandatory; name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

ID: 
The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ID have to be passed as JSON String.

SuiteFileName: 
The testsuite file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument. The SuiteFileName have to be passed as JSON String.

Environment: 
The suite environment can be setup/modified with this argument. The environment have to be passed as JSON Array with a list of environment key value pairs. First value of a pair is the environment key second the value.

TestPlans: 
A JSON Array with a list of testplan names. The testplans will be executed in the order defined in the array. If no testplan is given, all testplans included in the suite will be executed.

Resources: 
Within this argument you can pass resource descriptions for the execution.

Parameters: 
If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

JSON Argument Example:

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
"InfoString" "This is an example"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing or finished execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Wait for test execution finished Request ====

"host:9090/expeccoService/rest/waitForExecutionResult"

This request wait until the execution with the given job/ticket id is finished. After that it returns the same information as the request getExecutionInfo. With this request no polling on client side is necessary. On the other hand if the client poll the execution state with getExecutionInfo it is possible to fetch information about the progress of the execution from the response.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Get List of available Testsuites Request ====

"host:9090/expeccoService/rest/getListOfTestSuiteFiles"

This query returns a list of available Testsuites for execution. The suites will be searched in the directory passed at startup with the --suiteDirectory argument.

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request ====

"host:9090/expeccoService/rest/download"

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.

The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>

==== Perl Client ====
This is a small perl example. It starts a test execution on the expecco server and wait until execution is finished. In case of successful HTPP Response (200) the result is printed.

<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T08:21:36Z

Ab: /* Execution by Suite File Name Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job/ticket id
* SuiteFileName - mandatory; name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

ID: 
The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ID have to be passed as JSON String.

SuiteFileName: 
The testsuite file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument. The SuiteFileName have to be passed as JSON String.

Environment: 
The suite environment can be setup/modified with this argument. The environment have to be passed as JSON Array with a list of environment key value pairs. First value of a pair is the environment key second the value.

TestPlans: 
A JSON Array with a list of testplan names. The testplans will be executed in the order defined in the array. If no testplan is given, all testplans included in the suite will be executed.

Resources: 
Within this argument you can pass resource descriptions for the execution.

Parameters: 
If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

JSON Argument Example:

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
"InfoString" "This is an example"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Get List of available Testsuites Request ====

"host:9090/expeccoService/rest/getListOfTestSuiteFiles"

This query returns a list of available Testsuites for execution. The suites will be searched in the directory passed at startup with the --suiteDirectory argument.

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T08:20:26Z

Ab: /* Execution by Suite File Name Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job/ticket id
* SuiteFileName - mandatory; name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

ID:
The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ID have to be passed as JSON String.

SuiteFileName: 
The testsuite file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument. The SuiteFileName have to be passed as JSON String.

Environment:
The suite environment can be setup/modified with this argument. The environment have to be passed as JSON Array with a list of environment key value pairs. First value of a pair is the environment key second the value.

TestPlans:
A JSON Array with a list of testplan names. The testplans will be executed in the order defined in the array. If no testplan is given, all testplans found in the suite will be executed.

Resources:
Within this argument you can pass resource descriptions for the execution.

Parameters:
If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

JSON Argument Example:

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
"InfoString" "This is an example"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Get List of available Testsuites Request ====

"host:9090/expeccoService/rest/getListOfTestSuiteFiles"

This query returns a list of available Testsuites for execution. The suites will be searched in the directory passed at startup with the --suiteDirectory argument.

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T08:18:55Z

Ab: /* Execution by Suite File Name Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job/ticket id
* SuiteFileName - mandatory; name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

ID:
The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ID have to be passed as JSON String.

SuiteFileName:
The testsuite file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument. The SuiteFileName have to be passed as JSON String.

Environment:
The suite environment can be setup/modified with this argument. The environment have to be passed as JSON Array with a list of environment key value pairs. First value of a pair is the environment key second the value.

Testplans:
A JSON Array with a list of testplan names. The testplans will be executed in the order defined in the array. If no testplan is given, all testplans found in the suite will be executed.

Resources:
Within this argument you can pass resource descriptions for the execution.

Parameters:
If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

JSON Argument Example:

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
"InfoString" "This is an example"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Get List of available Testsuites Request ====

"host:9090/expeccoService/rest/getListOfTestSuiteFiles"

This query returns a list of available Testsuites for execution. The suites will be searched in the directory passed at startup with the --suiteDirectory argument.

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T08:16:24Z

Ab: /* Execution by Suite File Name Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job/ticket id
* SuiteFileName - mandatory; name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

ID: The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ID have to be passed as JSON String.

SuiteFileName: The testsuite file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument. The SuiteFileName have to be passed as JSON String.
Environment: The suite environment can be setup/modified with this argument. The environment have to be passed as JSON Array with a list of environment key value pairs. First value of a pair is the environment key second the value.
Testplans: A JSON Array with a list of testplan names. The testplans will be executed in the order defined in the array. If no testplan is given, all testplans found in the suite will be executed.
Resources: Within this argument you can pass resource descriptions for the execution.
Parameters: If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
** "generateLog" - JSON boolean as corresponding value element
** "generatePDFReport" - JSON boolean as corresponding value element

JSON Argument Example:
<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
"InfoString" "This is an example"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Get List of available Testsuites Request ====

"host:9090/expeccoService/rest/getListOfTestSuiteFiles"

This query returns a list of available Testsuites for execution. The suites will be searched in the directory passed at startup with the --suiteDirectory argument.

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T08:14:52Z

Ab:

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job/ticket id
* SuiteFileName - mandatory; name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

* ID: The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ID have to be passed as JSON String.
* SuiteFileName: The testsuite file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument. The SuiteFileName have to be passed as JSON String.
* Environment: The suite environment can be setup/modified with this argument. The environment have to be passed as JSON Array with a list of environment key value pairs. First value of a pair is the environment key second the value.
* Testplans: A JSON Array with a list of testplan names. The testplans will be executed in the order defined in the array. If no testplan is given, all testplans found in the suite will be executed.
* Resources: Within this argument you can pass resource descriptions for the execution.
* Parameters: If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
** "generateLog" - JSON boolean as corresponding value element
** "generatePDFReport" - JSON boolean as corresponding value element

JSON Argument Example:
<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
"InfoString" "This is an example"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Get List of available Testsuites Request ====

"host:9090/expeccoService/rest/getListOfTestSuiteFiles"

This query returns a list of available Testsuites for execution. The suites will be searched in the directory passed at startup with the --suiteDirectory argument.

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T05:56:44Z

Ab:

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Test Execution ====
===== Execution by Suite File Name Request =====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

===== Execute Request =====

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

==== Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T05:46:02Z

Ab: /* GetExecutionInfo Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Execution by Suite File Name Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID is returned (same as above execute-request).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== Status Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T05:44:18Z

Ab: /* ExecuteTestSuiteFileWithTestplanNames Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Execution by Suite File Name Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID is returned (same as above execute-request).

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T05:38:40Z

Ab: /* CleanupTempFiles Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Cleanup of Old Result/Log Files ====

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T05:37:26Z

Ab: /* CleanupTempFiles Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== CleanupTempFiles Request ====

"host:9090/expeccoService/rest/cleanupTempFiles"

Cleanup of Old Result/Log Files

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T05:36:24Z

Ab: /* Ping Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== CleanupTempFiles Request ====

"host:9090/expeccoService/rest/cleanupTempFiles"

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T05:35:25Z

Ab: /* RemoveTicket Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== Remove Ticket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== CleanupTempFiles Request ====

"host:9090/expeccoService/rest/cleanupTempFiles"

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

No argument. Returns an object containing status information.

 

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T05:34:47Z

Ab: /* KillExecution Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Terminate/Abort Request ====

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== RemoveTicket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== CleanupTempFiles Request ====

"host:9090/expeccoService/rest/cleanupTempFiles"

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

No argument. Returns an object containing status information.

 

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-13T05:33:20Z

Ab: /* RemoveTicket Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request ====

"host:9090/expeccoService/rest/killExecution"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request ====

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:
* ID - mandatory; job id

==== CleanupTempFiles Request ====

"host:9090/expeccoService/rest/cleanupTempFiles"

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

No argument. Returns an object containing status information.

 

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:58:07Z

Ab: /* Ping Request "/expeccoService/rest/ping" */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request ====

"host:9090/expeccoService/rest/killExecution"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request ====

"host:9090/expeccoService/rest/removeTicket"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== CleanupTempFiles Request ====

"host:9090/expeccoService/rest/cleanupTempFiles"

No argument. no return value.

==== Ping Request ====

"host:9090/expeccoService/rest/ping"

No argument. Returns an object containing status information.

 

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:57:24Z

Ab: /* Cleanup Request "/expeccoService/rest/cleanupTempFiles" */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request ====

"host:9090/expeccoService/rest/killExecution"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request ====

"host:9090/expeccoService/rest/removeTicket"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== CleanupTempFiles Request ====

"host:9090/expeccoService/rest/cleanupTempFiles"

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 
==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:56:25Z

Ab: /* RemoveTicket Request "/expeccoService/rest/removeTicket" */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request ====

"host:9090/expeccoService/rest/killExecution"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request ====

"host:9090/expeccoService/rest/removeTicket"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 
==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:55:42Z

Ab: /* KillExecution Request "/expeccoService/rest/killExecution" */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request ====

"host:9090/expeccoService/rest/killExecution"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 
==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:55:06Z

Ab: /* GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request ====

"host:9090/expeccoService/rest/getExecutionInfo"

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 
==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:53:42Z

Ab: /* executeTestSuiteFileWithTestplanNames Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== ExecuteTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 
==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:53:04Z

Ab: /* Execute Test Suite File */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== executeTestSuiteFileWithTestplanNames Request ====

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 
==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:50:30Z

Ab: /* Execute File Request "/expeccoService/rest/executeTestSuiteFile" */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Execute Test Suite File ====

"host:9090/expeccoService/rest/executeTestSuiteFile"

Load the testsuite and execute the testplans.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional
* TestPlans - optional
* Resources - optional
* Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 
==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:45:13Z

Ab:

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Execute File Request "/expeccoService/rest/executeTestSuiteFile" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 
==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.
=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:37:03Z

Ab: /* Execute File Request "/expeccoService/rest/executeTestSuiteFile" */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.

==== Execute File Request "/expeccoService/rest/executeTestSuiteFile" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs.
The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

<PRE>
{
"ID":"Testrun-4713",
"SuiteFileName":"E:\\tmp\\DemoTest2.ets",
"Environment":[
"TestDelay1" "60"
],
"TestPlans":[
"DefaultTestplan"
],
"Resources":[],
"Parameters":[
"generateLog" "true"
"generatePDFReport" "true"
]
}
</PRE>

==== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:21:32Z

Ab: /* ProtocolInfo Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.

==== Execute File Request "/expeccoService/rest/executeTestSuiteFile" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

The file must be present/reachable by the expecco slave.
It may be either an absolute pathname (typically on a shared network drive) or
a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

==== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:18:51Z

Ab: /* ProtocolInfo Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

* "host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"GET",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.

==== Execute File Request "/expeccoService/rest/executeTestSuiteFile" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

The file must be present/reachable by the expecco slave.
It may be either an absolute pathname (typically on a shared network drive) or
a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

==== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:09:47Z

Ab: /* ProtocolInfo Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

* "host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

<PRE>
{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"GET",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}
</PRE>

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.

==== Execute File Request "/expeccoService/rest/executeTestSuiteFile" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

The file must be present/reachable by the expecco slave.
It may be either an absolute pathname (typically on a shared network drive) or
a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

==== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T20:08:11Z

Ab: /* ProtocolInfo Request */

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

* "host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

{
"Version":2,
"URLPath":"expeccoService/rest",
"Protocol":[
{
"Name":"cleanupTempFiles",
"Request":"GET",
"Comment":"remove leftover temporary files."
},
{
"Name":"download",
"Request":"GET",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"download",
"Request":"PUT",
"Comment":"download a suite.",
"Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
},
{
"Name":"execute",
"Request":"PUT",
"Comment":"start execution; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFile",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"executeTestSuiteFileWithTestplanNames",
"Request":"PUT",
"Comment":"start execution of a well known suite; return ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
},
{
"Name":"getExecutionInfo",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String)"
},
{
"Name":"getListOfTestSuiteFiles",
"Request":"GET",
"Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
"Return":"Array"
},
{
"Name":"killExecution",
"Request":"GET",
"Comment":"kill execution of an execute job; argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"loadSuite",
"Request":"PUT",
"Comment":"load a suite.",
"Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
},
{
"Name":"ping",
"Request":"GET",
"Comment":"test reachability and return some status info.",
"Return":"Dictionary"
},
{
"Name":"removeTicket",
"Request":"GET",
"Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
"Argument":"(ID:String)"
},
{
"Name":"waitForExecutionResult",
"Request":"PUT",
"Comment":"get execution status of an execute job; argument is ticketID.",
"Return":"Dictionary",
"Argument":"(ID:String; ReportFiles:Array,)"
},
{
"Name":"protocolInfo",
"Request":"GET",
"Return":"Dictionary"
}
],
"Service":"ExpeccoRestService"
}

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.

==== Execute File Request "/expeccoService/rest/executeTestSuiteFile" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

The file must be present/reachable by the expecco slave.
It may be either an absolute pathname (typically on a shared network drive) or
a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

==== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T11:30:02Z

Ab:

== expecco REST Service Interface ==

If enabled, expecco accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

=== Start expecco with REST Server enabled ===

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of [[Starting_expecco_via_Command_Line#Command_Line_Options|the command line arguments]] for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

=== Introduction ===

The expecco REST service supports nearly the same set of operations as the [[Starting_expecco_via_Command_Line/en#Expecco_SOAP_Service_Interface|expecco SOAP service]], but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead.
Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via
"<code>host:9090/expeccoService/rest/protocolInfo</code>".

=== API Functions ===

A very useful REST-entry is the "<code>protocolInfo</code>" request, which returns a description of all supported REST call entries:

==== ProtocolInfo Request ====

"/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service).
It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:
* "Protocol" - an array containing one entry per supported call entry (see below).
* "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
* "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
* "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

* "Name" - the name of the rest call entry
* "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE"; currently always "GET"
* "Comment" - a comment describing the operation
* "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
* "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

{
"URLPath" : "expeccoService/rest" ,
"Service" : "ExpeccoRestService",
"Version" : 1 ,
"Protocol" :
[
{
"Name" : "execute" ,
"Request" : "GET" ,
"Argument" : "(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "start execution; return ticketID." ,
},
{
"Name" : "download" ,
"Request" : "GET" ,
"Argument" : "(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "start execution; return ticketID." ,
},
{
"Name" : "executeTestSuiteFile" ,
"Request" : "GET" ,
"Argument" : "(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)" ,
"Return" : "Dictionary"
"Comment" : "execute suite file; return ticketID." ,
},
{
"Name" : "getExecutionInfo" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Return" : "Dictionary"
"Comment" : "get execution status of an execute job; argument is ticketID." ,
},
{
"Name" : "killExecution" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Comment" : "kill execution of an execute job; argument is ticketID."
},
{
"Name" : "removeTicket" ,
"Request" : "GET" ,
"Argument" : "(ID:String)" ,
"Comment" : "give up execution of an execute job; if required, kill the job. argument is ticketID."
},
{
"Name" : "cleanupTempFiles" ,
"Request" : "GET" ,
"Comment" : "remove leftover temporary files."
},
{
"Name" : "ping" ,
"Request" : "GET" ,
"Comment" : "test reachability and return some status info." ,
"Return" : "Dictionary"
},
{
"Name" : "protocolInfo" ,
"Request" : "GET",
"Return" : "Dictionary"
}

]
}

==== Execute Request "/expeccoService/rest/execute" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteID - mandatory; the UUID of the test suite
* Suite - optional; suite data file (ets file) in base64 encoding
* SuiteURI - optional; the URL where expecco could fetch the suite
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

As described in the SOAP interface above, expecco caches downloaded suites in a temporary cache folder.
Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via
http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI.
If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder.
Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data),
or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request
with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if
it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements.
Currently supported keys are:
* "generateLog" - JSON boolean as corresponding value element
* "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements.
Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element
must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further
getExecutionInfo or terminateExecution requests (see below).

==== Download Request "/expeccoService/rest/download" ====

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed.
The argument is a JSON object with the following fields:
* SuiteID - mandatory String; the suite's ID
* Suite - optional String; base64 encoded .ets file
* SuiteURI - optional String; the URI from which expecco can fetch the suite
* Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.

==== Execute File Request "/expeccoService/rest/executeTestSuiteFile" ====

The details are the same as in the above SOAP variant.

The argument is a JSON object with the following fields:

* ID - mandatory; job id
* SuiteFileName - name of the testSuite file (ets file)
* Environment - optional;
* TestPlans - optional;
* Resources - optional
* Parameters - optional;

The file must be present/reachable by the expecco slave.
It may be either an absolute pathname (typically on a shared network drive) or
a relative filename. If a relative file name is given, it will be searched in the folder specified with the "''--suiteDirectory''" command line argument.

==== GetExecutionInfo Request "/expeccoService/rest/getExecutionInfo" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== KillExecution Request "/expeccoService/rest/killExecution" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== RemoveTicket Request "/expeccoService/rest/removeTicket" ====

The argument is a JSON object with the following fields:
* ID - mandatory; job id

The operation is the same as described in the previous SOAP section.

==== Cleanup Request "/expeccoService/rest/cleanupTempFiles" ====

No argument. no return value.

==== Ping Request "/expeccoService/rest/ping" ====

No argument. Returns an object containing status information.

 

=== Examples ===

==== Example Requests / Responses ====

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:
<PRE>
GET /expeccoService/rest/ping HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive
</PRE>

Response:
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"hello":"exeptn.bh.exept.de",
"restInterfaceVersion":"1",
"node":"fancy",
"osType":"osx",
"cpuType":"x86_64",
"osRelease":"10.8.0",
"architecture":"Darwin",
"system":"Darwin"
"numberOfCPUs":4,
"numberOfRunningTests":0,
"suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
"knownTestSuites":["test1.ets","test2.ets"],
"expeccoRelease":"2.7.0.0",

"pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
"SAP Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
"Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
"Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
"Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
"Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
"Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
"plugins"[...],
"expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
...
"expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}
</PRE>

Download request to expecco (without suite-info, to check if the suite is already loaded):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Response (empty, because suite is not present):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
}
</PRE>

Download request to expecco (with suite-info, to ensure suite is present):
<PRE>
GET /expeccoService/rest/download HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Connection: keep-alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (non-empty, because suite is now present on the expecco client machine):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}
</PRE>

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.
<PRE>
GET /expeccoService/rest/execute HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
"SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
"Suite":"... base64 encoded .ets suite file ..."
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Get progress and status information about a running test:
<PRE>
GET /expeccoService/rest/getStatusInfo HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Response (returns the execution's job ID):
<PRE>
HTTP/1.1 200 OK
Content-Type: application/json; charset="utf-8"
Content-Length: 4111
Connection: Keep-Alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}
</PRE>

Alternative execute-by-filename request (the suite-file must be present on the slave already):

<PRE>
GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1
Host: localhost:9123
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

{
"ID":"09ab0149-1234-9876-4583-1259a5e301f6",
"SuiteFileName":"c:\sharedSuites\test.ets"
}
</PRE>
==== Perl Client ====
<PRE>
use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';

$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test started ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
print "\n=== Test execution and result generation finished ===\n";
#my $response = from_json($client->responseContent());
#print Dumper($response);
} else {
print Dumper($client->responseContent());
}
</PRE>

Starting expecco via Command Line/rest/en

2017-03-12T11:22:53Z

Ab: /* Start expecco with REST Server enabled */

Starting expecco via Command Line/rest/en

2017-03-12T10:23:04Z

Ab: /* Introduction */