Oryon is an automation tool for Java applications (typically fat clients) which allows users to easily record and replay scenarios. During recording, a script is generated which will serve as the basis of the simulation. Advanced users can use the groovy programming language to enhance the script and add complexity to the automated scenario. Used in combination with STEP, Oryon can be involved in massively concurrent simulations involving thousands of clients and can benefit from the wide range of features provided by STEP itself (centralized results, collaborative web app, natural language bindings, etc).


An overview of Oryon’s architecture and components is provided in the diagram below:

Screen Shot 2018-06-21 at 14.14.48.png

The role and function of the different components are as follows:

  • The Oryon IDE serves as a script editor and requires to connect to the Oryon Agent in order to remotely control the target application. It retrieves information from the agent during the recording phase and sends commands to it during replay
  • The Oryon Agent runs alongside the target application client, captures events during recording, fires events during replay and communicates with the Oryon IDE
  • The Oryon Plugin for STEP allows users to turn their recorded scenarios (scripts) into full-blown Keywords in step


The first step is to configure your Java client in a way that allows Oryon’s Agent to run alongside it (as part of the same java process). This is done by adding the following command line option to the command line used to start your Java client:


after replacing the variables “path_to_your_agent_jar” and “path_to_your_agent_license_file” with the actual paths in your environment and setting an actual module name. For instance, assuming you’ve unzipped the oryon archive under C:\Tools\oryon and are using the Swing module, your command line option might look like this:


Once your Java application is running, you can start the Oryon IDE using the script startOryonIDE.bat and connect to the agent as follows:


IDE Functionality

Oryon’s IDE is a full blown groovy editor with additional functionality tailored specifically for Oryon such as:

  • an object tree representing the current state of the Java application currently connected through Oyron’s Agent (on the left side)
  • a main code editor pane on the top side
  • a console displaying the output of the script executions at the bottom

Recording a script

In order to record a script, you just need to hover over gui elements with your mouse and press the F6 key on your keyboard and pick an action from the pop-up menu. As a result, not only with the action be executed but a corresponding line of code will be generated in your IDE.

Another valuable feature is available through pressing the F7 key while hovering on a graphic element in the Java application, which will automatically reveal the location or position of this element in the hierarchal object tree on the IDE side.

You can repeat this process until you’ve reached the end of your scenario. Make sure to save your script when you’re done.


Replaying a script

In order to replay a script, load the file containing your script and press the play button. Alternatively, you can choose to only execute one code line at a time by selecting the code line and pressing play.


Interacting with the object tree

In addition to the hover + F6 approach on the Java application side, you can interact directly with the tree by clicking and right clicking on nodes and choosing from the same set of functions as you'll find in the F6-based list. If you enable Lookup mode (by clicking on the sunglasses icon), hovering over tree nodes will cause for the corresponding element to be framed in red in the Java application. This is particularly useful if you’re struggling to identify an element visually or if you want to examine the actual hierarchy of visual objects. You can also explicitely ask Oryon to highlight a given component by clicking the "Show in SUT" entry after right-clicking it.



Core API

The default language that Oryon scripts are generated in is groovy. This means that you can do anything that you would be able to do in the groovy programming language and thus, more generally, in Java. In addition to standard Groovy and JDK functionality, Oryon makes specific objects available to you through its own API. The following objects are especially useful:

  • gui : the basis object providing most of the primitives needed for locating and interacting with graphic objects
  • input : a key-value map of Java type "JsonObject" used to pass information which may vary from an execution to the next (typically, business information)
  • output : a key-value map of Java type "OutputMessageBuilder" used to return information which is necessary for assessing the correctness of the execution

The object "input" is of Java type "JsonObject". This type is documented here : https://docs.oracle.com/javaee/7/api/javax/json/JsonObject.html

The object "output" is of Java type "OutputMessageBuilder". This type is documented here: http://www.exense.ch/static/javadoc-grid-api/step/grid/agent/handler/context/OutputMessageBuilder.html

The following screenshots illustrate the way the editor and console behave when using input and output functionality and in the event of errors:



Module-specific APIs

Depending on the module you're using (Swing, FX, or product-specific), different primitives and semantics will be available to you. Standard primitives will be added in this section in the future as they're officially rolled out. Product-specific modules (i.e only strongly coupled with a certain vendor or application) are documented separately. Please request for the corresponding documentation to be sent to you via the usual support channels (most likely through our support portal at https://exense.atlassian.net/ ).

Using XPath to locate elements

The way Oryon identifies components is through their position in the tree-based representation of the Java application's state, and also by inspecting various properties within the nodes of that representation. The library and syntax used for this purpose is called “XPath” which you can find more information about here.

As you record a scenario and add code lines to your script, you'll see that Oryon automatically generates these XPaths. An interesting feature of Oryon is the ability to immediately validate XPath correctness by clicking it. If the XPath is highlighted in green, it means that it was successfully matched by the agent with a visual object (GUI component) in the Java application.

Warning: in various cases, and even if Oryon found a match, it could be that the matched element is not the one you expect to be found as a user, it is therefore up to the user or script developer to fix incorrect or broken XPaths.


The following screenshots show the way the console output behaves when no element or multiple elements are matched:



Integration with STEP

Once you’ve recorded scripts using the IDE, you have the ability to register those scripts as keywords in STEP by following the steps listed below:

  1. Add the oryon plugin to the lib folder of your controller in order to unlock Oryon scripts as a Keyword type
    • this step is actually obsolete since v3.6.4, as plugins are automatically provided

  2. Configure your keyword and bind it to the groovy script
  3. Add the following variables to your controller’s and agent’s properties:


plugins.oryon.home=/path/to/oryon-x.y.z => used by the plugin to access the oryon libraries
plugins.oryon.errorhandler=../data/scripts/oryon_errorhandler.groovy => can be used to define a script that is executed in case of TECHNICAL_ERRORs during the keyword execution


{ "gridHost": "", "registrationPeriod": 1000, "gridReadTimeout": 20000, "workingDir": "src/test/work", "tokenGroups": [ { "capacity": 10, "tokenConf": { "attributes": { "key": "val" }, "properties": { "plugins.oryon.home": "/path/to/oryon/oryon-x.y.z", "application.startcmd": "java.exe {oryon-agent} -jar myapp.jar" => the start command of the target application. IMPORTANT: do not forget the placeholder {oryon-agent} } } } ], "properties": { } }

Lastely, you need to implement a login keyword using the OryonDriver API and make that you've set the "application.startcmd" and "plugins.oryon.home" properties correctly inside the AgentConf.js. The Driver documentation is provided here:


Custom libraries

In order to use your own libraries or add third party libraries to your Oryon project, the best way is to copy the corresponding Jar files to the lib folder located within your Oryon home. Your Oryon home is located via the property plugins.oryon.home in the step.properties file of your controller configuration and in the AgentConf.json file of your agent(s).

Created by Dorian Cransac on 2018/06/21 13:34
Copyright © exense GmbH