Prerequisites

STEP Keyword development requires at least Java 8 SDK installed on your machine. Depending on your platform, they are various ways to install it :

  • Windows
    refer to the official website and follow the instructions : Oracle Java download
  • Debian / Ubuntu
    execute the following command as root : apt-get install default-jdk
  • Mac OS
    refer to the official website and follow the instructions : Oracle Java Max OS installation

Getting started with Keyword development

We'll be using Java as our default language and platform and Maven as our dependency management and build tool in this series of examples, but the same can be achieved in other languages supported by step (JS, .Net, etc) as long as the dependencies are correctly downloaded and linked.

Setting up Maven

Dependencies

We have made a public maven artefact available on our nexus for the developer's convenience. Make sure to replace the "version" setting with the version of STEP you want to develop Keyword for :

<dependency>
<groupId>ch.exense.step</groupId>
<artifactId>script-dev-java</artifactId>
<version>3.10.0</version>
</dependency>

Maven Repository

Exense's public repository (http://nexus.exense.ch/nexus/content/repositories/releases) is deprecated. As of version 3.6.1 (and upwards), you should now be able to pull our dependencies straight out of the public sonatype repository.

We recommend also to setup the Maven compiler plugin to use Java 8 :

<build>
<plugins>
 <plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.1</version>
  <configuration>
   <source>1.8</source>
   <target>1.8</target>
  </configuration>
 </plugin>
</plugins>
</build>

So finally your "pom.xml" should look like :

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example.step</groupId>
<version>0.0.1-SNAPSHOT</version>
<artifactId>scripts-keyword-demo</artifactId>

<dependencies>
 <dependency>
  <groupId>ch.exense.step</groupId>
  <artifactId>script-dev-java</artifactId>
  <version>3.10.0</version>
 </dependency>
</dependencies>
<build>
 <plugins>
  <plugin>
   <artifactId>maven-compiler-plugin</artifactId>
   <version>3.1</version>
   <configuration>
    <source>1.8</source>
    <target>1.8</target>
   </configuration>
  </plugin>
 </plugins>
</build>
</project>

Basic example

The following examples apply to all languages supported by step (i.e, Java, .NET, JS/nodeJS, etc). Syntax may vary due to the language's own specifics but the objects exposed to the developer won't.

For Java, which will be our default platform for examples in the documentation, make sure your Keyword class extends step's class step.handlers.javahandler.AbstractKeyword and that your dependencies have been set up.

Code

In the following example we will create a simple keyword waiting for a period passed into the Input and adding to the Output a boolean with a value of true.
Here the code :

package com.example.step;

import step.handlers.javahandler.AbstractKeyword;
import step.handlers.javahandler.Keyword;

public class KeywordDemo extends AbstractKeyword {

// Annotation tells step that this function can be used as a Keyword
@Keyword()
public void Sleep() throws NumberFormatException, InterruptedException {
 // Waiting for the period passed in Input
 Thread.sleep(Long.parseLong(input.getString("sleep")));
 // Add a boolean object to the Output
 output.add("success", true);
}
}

Testing the keyword locally

Here's an example of how you can run your keyword locally as a JUnit test:

@Test
public void KeywordTest() throws Exception{
ExecutionContext ctx = KeywordRunner.getExecutionContext(properties, this.getClass());

Output<JsonObject> output = ctx.run("Sleep", "{\"sleep\":\"100\"}");
System.out.println(output.getPayload());
}

As a result of the execution, you should be able to see the following message in your console :

2019-01-11 15:47:07,481 DEBUG [main] s.h.j.KeywordHandler [KeywordHandler.java:91] Invoking method Sleep from class com.example.step.KeywordDemo loaded by sun.misc.Launcher$AppClassLoader@b4c966a

{"success":true}

Packaging and deployment

You can now package your class into a single Jar file using Maven.
For this you can use the following command after changing directory to the one containing you Java class (note that you can also use your IDE in order to generate the Jar file):

mvn clean install

This will generate the Jar file you now needs to copy into the installation path of your Controller, for example in data/scripts/ :

JarFile.png

You can now register the keyword into step. For this, go to the Keyword tab, click on New Keyword and fill properly the required fields :

CreateKeyword.png

Note: jar files can also be dragged and dropped into the input box or uploaded programmatically via REST or our Remore Java Client

You can now test your keyword by clicking on the run button and fill the Input value properly :

TestKeyword.png

Keyword API

Reading Input

A Keyword's input is a JsonObject. We've chosen to let the developer choose the type of their arguments. This means that reading an argument from within a keyword will have to be done according to that type, otherwise the Json reader will throw an error.

Here's are a couple of examples assuming you've passed the following Json as an input:

ExecutionContext ctx = KeywordRunner.getExecutionContext(properties, this.getClass());
// { "url" : "http://step.exense.ch", "index" : 3 }
Output<JsonObject> output = ctx.run("MyKeyword", "{\"url\":\"http://www.exense.ch\", \"index\" : 3 }");

Inside the Keyword, you can then retrive your inputs like this:

String homeUrl = input.getString("url");
int elementIndex = input.getInt("index",1);

Which would look like this if you're executing this from a test plan:

DemoKeyword.png

Error handling

step makes a difference between errors which are internal (called "TECHNICAL_ERROR") and business errors (resulting in the status "FAILED"), which are derived from the evaluation of Check controls. In order to produce clean reports and leverage this distinction, we recommend catching any exception being thrown from within your keywords and handling the situation by attaching information to the output object.
You can even attach binary content or the exception stack trace to the object by doing so:

output.addAttachment(AttachmentHelper.generateAttachmentForException(e));

Session

step provides the ability to store data in a session object. This object usually only makes sense when a Session control is used inside the test plan. The session object becomes very useful when passing information or technical objects between keywords (see for example the way we use Selenium's driver in the next section), especially if the data is difficult or impossible to serialize and de-serialize via the input/output mechanism.

You can set any kind of data (primitive types or collections) in the session object by doing so :

@Keyword(name="PutToSession")
 public void putToSession(){
   session.put("string_key", "Here is my value");
   session.put("int_key", 3);
 }

You can then access your data the same way, but you'll have to cast the data manually back to its original type :

@Keyword(name="GetFromSession")
 public void getFromSession() {
   output.add("my_string_value", (String) session.get("string_key"));
   output.add("my_int_value", (int) session.get("int_key"));  
 }

If you're using a collection, see the method Arrays.copyOf to convert all of its content at once back to the original type.

You can then create a test plan using the "Session" control in order to pass the session information trough the Keywords :

1520339703046-945.png

Once you executed the plan you can see as a result that the session objects have been properly retrieved and displayed as output :

1520339785847-159.png

Selenium example

Selenium framework provides the ability to automate browsers actions (browsing, clicking, filling forms etc...) and is used a lot for automation testing.
You can find more information on the official Selenium website.

Maven settings

Using the script-dev-selenium artefacts

We've made a public maven artefact available on our nexus for the developer's convenience. This artefact allows you to develop Selenium Keywords without having to manage the Selenium version explicitly, but with the version embeded in Step (Version 2.53.1 for Selenium 2 and 3.5.3 for Selenium 3). 

Depending on which version of Selenium you intend to use, you can choose from the following two dependencies:

  • Version 2
<dependency>
    <groupId>ch.exense.step</groupId>
    <artifactId>script-dev-selenium-2</artifactId>
    <version>3.10.0</version>
    <type>pom</type>
</dependency>
  • Version 3
<dependency>
    <groupId>ch.exense.step</groupId>
    <artifactId>script-dev-selenium-3</artifactId>
    <version>3.10.0</version>
    <type>pom</type>
</dependency>

You will then be able to create your Selenium Keywords by choosing the Selenium Type and the proper major version:

1554131223843-534.png

Using Selenium as a library

If you want more flexibility for managing your Selenium versions (multiple versions per controller, ...), you can create a library containing the needed dependencies with the following pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>my.project.example</groupId>
    <artifactId>selenium-dependencies</artifactId>
    <packaging>jar</packaging>
    
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <selenium.version>3.14.0</selenium.version>
    </properties>
    
    <dependencies>
      <dependency>
          <groupId>org.seleniumhq.selenium</groupId>
          <artifactId>selenium-api</artifactId>
          <version>${selenium.version}</version>
      </dependency>
      <dependency>
          <groupId>org.seleniumhq.selenium</groupId>
          <artifactId>selenium-java</artifactId>
          <version>${selenium.version}</version>
      </dependency>
    </dependencies>

    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-shade-plugin</artifactId>
          <version>3.2.1</version>
          <executions>
            <execution>
              <phase>package</phase>
                <goals>
                  <goal>shade</goal>
                </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
</project>

You will then be able to create your Selenium Keywords by choosing the Java Type and adding the generated jar as a library:

1554131366662-800.png

Code

In the following example we will create a simple keyword which is going to create a WebDriver, navigate to the url passed in Input and finally check if one of the h1 balise contains the text "Discover". Here the code :

@Keyword(name="Selenium_Example")
public void Selenium_Example() {
   // In this example we will use Chrome, so we explicitly set the location of its web driver
   System.setProperty("webdriver.chrome.driver", "C:\\Tools\\chromedriver.exe");
   // Create a new driver object in order to execute actions
   ChromeDriver chrome = new ChromeDriver();
   // Get the url value from the input
   String homeUrl = input.getString("url");
   // Navigate to the url
   chrome.navigate().to(homeUrl);
   // Look for an h1 balise containing the text "Discover"
   chrome.findElement(By.xpath("//h1[contains(text(),'Discover')]"));
}

WebDriver Management

Regarding webdriver management, we've opted to not force a certain lifecycle management approach onto the developer, but instead let them decide how and when they want to store the driver.

However we have strong recommendations and best practices to offer in that department :

  • for beginners who are using Selenium or step on their first attempt, we recommend packing the whole scenario including driver creation and destruction in a single keyword and playing around with the API until they've built a basic test plan that does what they expect
  • for more advanced users or load testers who need to have more control over driver creation and destruction and not tie these steps to the rest of the workflow, we encourage you to:
    • create explicit Keywords for the creation and destruction of the driver and implement the rest of the workflow's logic in (a) separate keyword(s)
    • work in "stateful" mode by introducing a Session object in your test plan, which will garantee at runtime that the context of each thread / virtual user is maintained and isolated from the others
    • this will allow you to add a For loop object and have your users iterate in a certain scenario without destroying the driver (and if you wish, without logging out)
    • attach the driver object to step's session object, which is managed internally by step and will allow for the "business keywords" to use a properly initialized driver (see example below)
    • we also recommend wrapping the driver in a class which implements Closable to help step clean up in error scenarios (see below as well)
  • lastly, in order to achieve maximum Keyword granularity (and reduce maintenance efforts), especially in environments involving many partially overlapping workflows, we recommend separating each logical step of the workflow in distinct Keywords and passing the driver between keywords

Driver Wrapper class

First let's take a look at our DriverWrapper class :

public class DriverWrapper implements Closeable {
// Our driver object
final WebDriver driver;
// Constructor assigning the given driver object to the local one
public DriverWrapper(WebDriver driver) {
        this.driver = driver;
}
// Implementing the Closeable interface requires to override the close() method, this is where we destroy the driver object
@Override
public void close() throws IOException {
  driver.quit();
}
}

Full Selenium example class

We can now work on our Selenium class, which will define 3 Keywords :

  • OpenChrome
    - will be used to create the driver object and the driver wrapper, and pass the driver wrapper to the step's session
  • NavigateTo
    - will be used to navigate to an url passed via the input
  • CloseChrome
    - will be used to explicitly close the driver

Here the entire class code :

public class SeleniumExample extends AbstractKeyword {
// Private method in order to get the WebDriver from the DriverWrapper object
final WebDriver getDriver() {
 return session.get(DriverWrapper.class).driver;
}
 
@Keyword(name="OpenChrome")
public void OpenChrome() throws Exception {
 // Set explicitly web driver location
 System.setProperty("webdriver.chrome.driver", "C:\\Tools\\chromedriver.exe");
 // Create the driver object
 final WebDriver driver = new ChromeDriver();
 // Tell the driver to timeout after 10 seconds
 driver.manage().timeouts().implicitlyWait(10, TimeUnit.SECONDS);
 // Put the DriverWrapper object into step's session
 session.put(new DriverWrapper(driver));
}
 
@Keyword(name="NavigateTo")
public void NavigateTo() throws Exception {
 // Check if the Input contains the url
 if(input.containsKey("url")) {
  // Get the driver from step's session
  final WebDriver driver = getDriver();
  // Navigate to the provided url
  driver.navigate().to(input.get("url").toString());
 } else {
   output.setError("Input parameter 'url' not defined");
 }
}

@Keyword(name="CloseChrome")
public void CloseChrome() throws Exception {
 // Get the driver from step's session
 final WebDriver driver = getDriver();
 // Close explicitly the driver
 driver.quit();
}
}

We can now deploy and create our Keywords as described in the previous section and create a test plan using them :

1520350152966-795.png

Tags:
Created by Jerome Brongniart on 2019/03/11 13:43
     
Copyright © exense GmbH
v1.0