Categories: PLUGINS

SikuliX Plugin

SikuliX is a simple but efficient open source tool for UI automation. It provides an intuitive IDE to record and replay UI automation scripts based on image and text recognition.

The SikuliX plugin for Step enables the out-of-the-box integration of SikuliX scripts in Step. The combined power of Step and SikuliX enables all-round UI automation at scale and makes it possible to create simple UI automation scripts and use them for Synthetic Monitoring, RPA, Performance Tests and all other features covered by Step.

It supports following features:

  • Passing of Keyword inputs to SikuliX
  • Passing of Parameters (properties) to SikuliX
  • Returning keyword outputs, errors and measurements
  • Attachment of the SikuliX logs, screenshot, and optionally attaching the whole work folder

This page describes how to install, configure and use the SikuliX plugin for Step.

Installation

The SikuliX plugin is part of the Enterprise edition of Step and enabled per default on Step Enterprise. The distribution of Step embeds the version 2.0.5 of SikuliX and is preconfigured to work on most setups without any additional configuration.

To use a different version of SikuliX in Step, you can define the path to the sikuli IDE jar (sikulixide-x.y.z.jar) in the conf/step.properties file of the Step Controller:

plugins.sikulix.jar=/path/to/sikulixide-x.y.z.jar

Usage

Recording a SikuliX Keyword

  1. Download the SikuliX IDE on the machine you’d like to record your automation script
  2. Open the SikuliX IDE
  3. Record your script
  4. Export your script as Jar while clicking on File > Export as jar
  5. Go to Step, create a Keyword and upload your SikuliX script

Passing variables to SikuliX

Keyword Inputs and Properties are passed to SikuliX via files. Two files in different format are made available in the SikuliX work folder.

Variables as Properties file

The file step_keyword_input.properties is written to the SikuliX work folder as a Properties using a key=value syntax. It contains both the keyword’s properties and the keyword’s inputs. In case the same variable is defined in both inputs and properties, the inputs take precedence.

Example of content:

username=user123
password=pass123
array=[1,2]
map={"nestedField1"\:1}

Variables as JSON file

The file step_keyword_input_message.json is written to the SikuliX work folder as a JSON object separating the keyword’s inputs and the keyword’s properties. Example of content:

{
  "inputs": {
    "username":"david",
    "age":13
  },
  "properties": {
    "debug": "true"
  }
}

Providing Keyword results

Attachments

In case of error or by setting the debug property to true, the SikuliX log and a screenshot taken at the end of the executions are automatically attached to the report. Additionally, the property attachWorkFolder can be set to true to automatically attach the content of the work folder as a ZIP archive to the report.

Results as properties file

This format only allows to pass keyword’s output in the format key=value as in below example:

extractedText1=this is an example
extractedText2=this is an example

Results as JSON file

With the JSON format, keyword’s outputs, errors and measurements can be defined as described in below example. Note that the payload objects represent the keyword’s outputs:

{
  "payload": {
    "provided_age": 13,
    "provided_debug": true,
    "provided_username": "david"
  },
  "error": {
        "msg": "Some unexpected technical error", 
        "code": 0, 
        "type": "TECHNICAL" //either TECHNICAL OR BUSINESS
    }, 
    "measures": [
        {
            "data": { //Optionally enriching the measurements with custom data for indepth analytics
                "username": "david"
            }, 
            "duration": 100, //duration in milliseconds
            "name": "my custom measure", 
            "begin": 1731925827847 //Epoch time in milliseconds
        }, 
        {
            "duration": 200, 
            "name": "my other custom measure", 
            "begin": 1731925827847
        }
    ]
}

SikuliX Script example with Properties files

Following example illustrate how to read and use keyword’s input and properties as a Properties file as well as how to write keyword’s output in the same format. Note that you way mix both format (JSON and properties) between inputs and outputs.

from java.util import Properties
from java.io import FileInputStream
from java.io import FileOutputStream

# Load the Step properties file containing keyword inputs and properties
properties = Properties()
stream = FileInputStream("step_keyword_input.properties")
try:
    properties.load(stream)
finally:
    stream.close()  # Ensure the stream is closed after loading

# Access properties
username = properties.getProperty("username")
password = properties.getProperty("password")

# Write keyword outputs as properties file
outputProperties = Properties()
outputProperties.put("username",username)
outputProperties.put("password",password)
stream = FileOutputStream("step_keyword_output.properties")
try:
    outputProperties.store(stream, "Keyword outputs")
finally:
    stream.close()  # Ensure the stream is closed after storing

SikuliX Script example with JSON files

Following example illustrate how to read and use keyword’s input and properties as a JSON file as well as how to write keyword’s output, errors and measures in the same format. Note that you way mix both format (JSON and properties) between inputs and outputs.

import json

# Read the JSON file containng the keyword inputs and properties
file_path = "step_keyword_input_message.json"

with open(file_path, 'r') as file:
    data = json.load(file)  # Convert JSON to a Python dictionary

#Get inputs and propreties
username = data["inputs"]["username"];
age = data["inputs"]["age"];
debug = data["properties"]["debug"]

# Print out values as illustrations
print("username: ", username );
print("age: ", age);
print("debug: ", debug);


# define keyword outputs
outputs=dict()
outputs["provided_username"] = username;
outputs["provided_age"] = age;
outputs["provided_debug"] = debug;
#define error
error=dict(type="TECHNICAL",msg="Some unexpected technical error",code=0)
#define measures with custom data for analytics
measure1=dict(name="my custom measure",begin=int(time.time() * 1000),duration=100,data = dict(username=username))
measure2=dict(name="my other custom measure",begin=int(time.time() * 1000),duration=200)
measures=[measure1,measure2]

outputMessage=dict(payload = outputs, error = error, measures = measures)
print("outputMessage content:", outputMessage)

# Serialize custom object to JSON
with open("step_keyword_output_message.json", 'w') as json_file:
    json.dump(outputMessage, json_file, indent=4)

See Also