This section will focus on registering and using already developed keywords. To get started with Keyword development check out the related pages in the Developer guide.

Keyword Basics

In step, keywords are the primary building blocks implementing your automation. They are objects which carry the mapping between a piece of business logic in an application and the corresponding simulation routine. It might represent a fully automated flow or be of a finer granularity such as a single user action or service call. Using a finer granularity is usually preferable to increase the reusability in multiple business flows through Plans. When developing a keyword, the developer can use the input and output objects for exchanging values with the keyword user.

Keyword Types

Keywords can be of different types. The type is used to specify detail about the routine that the keyword implement, like the language utilized for developing the routine (Java, C#,…) or the sort of plugin used (PDF test, QF-test, …). The following types are available:

Language-based Keyword types

Most of the keywords you will want to use will be based on your own piece of code. The main keyword types will allow you to specify the language used by your keywords. Currently, this can be:

• Script: These keywords will be executed on Java agents. Thanks to the Java’s ScriptEngine, you can write keywords in
  • Java using the keyword api as described for instance in this tutorial.
  • Groovy directly in the step Web UI. You may find some groovy code samples that can be wrapped into keywords in our library.
  • Javascript is now deprecated. See NodeJS keywords if you need to write your automation code with javascript.
• NodeJS: These keywords will be NodeJS functions and will be executed on NodeJS agents. Check the related plugin documentation for more details.
• .Net: These keywords are C# based functions and will be executed on .NET agents. The detailed documentation is available under the corresponding plugin section, and is illustrated in the .Net tutorials: AutoIt with step.

Composite Keywords

The second most important type of keyword is the composite keyword. Composites are logical keywords, containing references to other keywords. Composite keywords will help you write cleaner and more modular execution suites, instead of clumping up everything in a single plan. The main goals are to:

• Provide a form of alias for groups of keywords which are often executed together.
• Wrap a keyword with a specific set of inputs and output-checks, thus isolating a specific case into its own keyword.

Composites also have their own control, the Return. This control allows you to output values as you will do with other keyword types.

Plugin-based Keywords

These types of keywords are defined by some step plugins and allow integrating with other products:

• PDF Test: A keyword for comparing PDFs. See here.
• SoapUI: A keyword allowing to execute of a SoapUI project. See here.
• JMeter: A keyword for executing a JMeter Test Plan. See here.
• QF-Test: A keyword representing the execution of a QF-Test Testsuite.
• Oryon: A keyword representing the execution of an Oryon keyword.
• Cypress: A keyword allowing to run cypress commands. See here.

Local functions

Finally, a set of local functions are included by default with step. The following keywords exist:

• Echo: will simply echo the pairs of key/value given in input
• PDF_compare: A generic Keyword for pdf comparison, more detail is available here. Note: This is only available for enterprise users and need a dedicated license.
• EBC_Put, EBC_Peek and EBC_Get: Basic Keywords for putting and retrieving events from the Event Broker. Note: This is only available for enterprise users and need a dedicated license.
• InsertMeasurement: can be used to insert arbitrary transaction measurements into RTM from a plan instead of from within a Keyword’s code.

Keyword deployment

Keyword Package approach

For basic keyword deployment, please jump to the next section.

Keyword Packages allow managing Keywords in a batch way. They are the most efficient and practical way to manage Keywords at industrial scale.

Key concepts

Autodiscovery

The main idea is that step will automatically discover Keywords and create entries for every Keyword found in the package. step will parse the content of resources to find methods annotated with the Keyword type and use this information to generate the corresponding entries in the Keyword collection.

Resource mapping

Each package is bound to a Jar resource (for Java), or a DLL resource (for .NET). Upon uploading your resource, the list of found Keywords will be presented, and you’ll then be able to decide whether to import these Keywords. Keywords tied to a Keyword Package will then be modified via batch updates when users perform actions at the Package level.

Deploying a Keyword Package

From the Keyword view, clicking the New Keyword Package button will summon a dialog allowing for the upload of a resource (Jar or DLL) or maven snippet of a repository artifact:

You can then drag & drop your resource (and eventually needed libraries) into the package field:

Which should result in the list of contained keyword to be automatically populated and presented to you:

After clicking save, your new Keywords are now part of the Keyword view, and the right-most column provides you with information regarding the package they are bound to:

If you prefer working with maven artifacts you can simply copy the maven snippet from the maven repository of your choice:

And paste it in the input field:

Per default step will search for the artifact in the maven central repository. Additional repositories and proxies can be configured in step.properties.

Keyword Package Versioning

When managing multiple versions of the same package, it is necessary to add a new parameter to the functionTable screen template.

This new parameter will be automatically added in the Keyword configuration screen and allows you to distinguish between two versions of the same keyword:

Keyword Package Routing

When configuring your keyword package, you have the possibility to define routing rules for all Keywords managed by this package such as:

• Execute on controller: all keywords will be executed directly on the controller rather than on agents
• Agent token selection criteria: route the execution of the keywords on specific agents, see the keyword routing documentation for more details

Reusing attributes from an existing packages

When creating or updating your keyword package, you can choose to reuse the attributes of another keyword package, so-called “Reference Keyword package”.

If you choose to do so, all the Reference Package Keywords custom configurations (schema, call timeout etc…) will be applied to the Keywords of the package you are creating / updating.

Adapting the keyword selection to the versioning

If multiple versions of the same keywords exist, and you run your plan using plain text plans or plugins based on such plan like the ALM plugin, you will need a mechanism to select the proper version of your Keyword. This can be done with the configuration property step.repositories.parser.attributes.mapping defined in step.properties.

This parameter takes a semicolon-separated list of coma-separated tuples (i.e., …=param1.1,param1.2;param2.1,param2.2;…), where the first value of the tuple is a functionTable parameter, and the second value is any parameter that can be evaluated by step.

Example: Let suppose your functionTables contains the parameter “attributes.version”.

• If you define the following global parameters:

• Then configure the step property as below:

  step.repositories.parser.attributes.mapping=version,version_selector;

Then step will select the version 2.0.0 of your Keyword if you execute your test with the execution parameter “Environment” equal to “PROD”, and the version 1.0.0 if you execute it with “Environment” at “TEST”

Updating a package

From the Keyword view, mouse over the package name of any Keyword entry bound to the package and click the wrench icon:

You can then re-upload your resources into the Keyword package and libraries fields, which will automatically update the revision of the resource and all the corresponding Keywords.

Deleting a package

In order to delete a package, mouse over the package name of any Keyword entry bound to the package and click the trashcan icon:

Manual registration approach

In order to use your Keywords with step, you need to register them. This can be done via the web interface or the Java API and is based on a generic and type specific information.

Generic registration

Registering a new Keyword using the visual editor is done through the New Keyword button on the Keywords tab. This will popup the following registration form:

The following fields are generic to all Keyword types:

• Name The name of the Keyword. It will allow to reference this keyword. For Java (resp. C#), this field must match the name given in the annotation (resp. the attribute).
• Description The description of the keyword. It allow to put more details / explanation about the keyword in a free text field.
• Type The type of the Keyword. Changing the type will also change the type specific fields (indicated in the screenshot in red).
• Schema The JSON schema allows to validate the inputs. With this field you can specify the name of your Keyword inputs, their types, define mandatory inputs … The following example comes from the PDF_Compare Keyword:

{"properties": {
		"actual":{"type":"string"},
		"expected":{"type":"string"},
		"masks":{"type":"string"},
		"unsortedPagesTolerance":{"type":"string"}
	},
	"required":["actual","expected"]}

• Agent token selection criteria A list of agent attributes allowing to perform basic Keyword Routing, restricting the set of agents that can execute this Keyword to the ones with the specified attributes.
• Call timeout (ms) The maximum duration (in milliseconds) of a keyword execution. If the keyword execution last for more that this timeout, the controller will report an error and the agent will try to interrupt the keyword.

Registering a Keyword is not possible using the natural language interface. Keywords have to be registered using the web interface or the Java remote client

The following code snippet shows how to register a Java Keyword using the remote client. Note that:

• In this example, the client object is a step.client.StepClient connected to your controller.
• A Keyword is called a Function internally.
• In this example we use the step.plugins.java.GeneralScriptFunction Keyword type. You will find the list of available types in the next section, or you can also find this list by checking in your IDE for all the classes extending the base class step.functions.Function:

try (RemoteFunctionManagerImpl functionClient = (RemoteFunctionManagerImpl) client.getFunctionManager()) {
  // We use here a GeneralScriptFunction for creating a Keyword of type "script":
  GeneralScriptFunction keyword = new GeneralScriptFunction();
  keyword.setId(new ObjectId());
  // We define some attributes:
  Map<String, String> attributes = new HashMap<>();
  attributes.put(Function.NAME, "Demo_Keyword_Java");
  attributes.put("app", "AppName");
  keyword.setAttributes(attributes);
  // We set it as a Java keyword and indicate the path to the jar file
  // The script language can also be "javascript" or "groovy":
  keyword.setScriptLanguage(new DynamicValue<String>("java"));
  keyword.setScriptFile(new DynamicValue<String>("/.../demo-java-keyword.jar"));
  // finally, we save the keyword on the controller:
  functionClient.saveFunction(keyword);
}

Type specific fields

This section lists the set of attributes for each Keyword type.

Language-based Keyword types

For Script (Java, JS, Groovy, etc), the following fields are needed:

• The language used (Java, Javascript or Groovy)
• The script/Jar file containing the Keyword.
• An optional library, containing the Keyword dependencies.

Note the file selector allows you to directly drop files via the GUI, lookup and update existing resources and download your files.

For .NET, and similar to Java, a zip of all required dependencies (i.e, other DLLs as well as PDB files) can be provided in the library field, and the keyword’s own DLL file is to be dragged into its own field (or via absolute path if you wish to reference a local file on the controller)

For Node.js, a folder containing a NodeJS project is needed. This folder must contain a sub-folder named keywords, containing a keywords.js file. You can specify this folder as a path accessible from the controller or as a zip file that you can drop on the GUI. You can look at the github of the agent for an example of such project.

Registering a keyword is not possible using the natural language interface. Keywords have to be registered using the web interface or the Java Remote Client

The following classes have to be used when registering a script keyword via the API:

• step.plugins.java.GeneralScriptFunction for Java or script keywords. The following setters exist:

GeneralScriptFunction keyword = new GeneralScriptFunction();
keyword.setId(new ObjectId());
Map<String, String> attributes = new HashMap<>();
attributes.put(Function.NAME, "Demo_Keyword_Java");
keyword.setAttributes(attributes);
//
keyword.setScriptLanguage(new DynamicValue<String>("java"));
keyword.setScriptFile(new DynamicValue<String>("/.../demo-java-keyword.jar"));
keyword.setLibrariesFile(new DynamicValue<String>("/.../dependencies.jar"));

• step.plugins.dotnet.DotNetFunction for C# based keywords. The following setters exist:

DotNetFunction keyword = new DotNetFunction();
keyword.setId(new ObjectId());
Map<String, String> attributes = new HashMap<>();
attributes.put(Function.NAME, "Demo_Keyword_Net");
keyword.setAttributes(attributes);
//
keyword.setDllFile(new DynamicValue<String>("/.../demo-net-keyword.dll"));

• step.plugins.node.NodeFunction for NodeJS based keywords. The following setters exist:

NodeFunction keyword = new NodeFunction();
keyword.setId(new ObjectId());
Map<String, String> attributes = new HashMap<>();
attributes.put(Function.NAME, "Demo_Keyword_JS");
keyword.setAttributes(attributes);
//
keyword.setJsFile(new DynamicValue<String>("/.../demo-js-keyword.js"));

Composite Keywords

For a Composite keyword, the only needed field is the Plan to be executed. The list of existing Plans will be displayed for selection when choosing select. You can also edit the plan via the pen button:

Registering a keyword is not possible using the natural language interface. Keywords have to be registered using the web interface or the Java Remote Client

The following classes have to be used when registering a composite keyword via the API:

• step.plugins.functions.types.CompositeFunction for composite keywords. The following setters exist:

CompositeFunction keyword = new CompositeFunction();
keyword.setId(new ObjectId());
Map<String, String> attributes = new HashMap<>();
attributes.put(Function.NAME, "Demo_Keyword_Composite");
keyword.setAttributes(attributes);
//
keyword.setArtefactId(new DynamicValue<String>("5bc73a2b23a34f000e4a6fb0"));

Plugin-based Keywords

Here is a quick list of the needed fields and links to the keyword API for the major plugins:

Enforcing requirements

In order to improve the quality of interactions between Keyword users and developers and limit errors due to input mismatches, users and developers can agree on mandatory information required to run any given Keyword.

Schema

Optional and mandatory input keys can be specified in the form of a JSON schema tied to the Keyword. This schema can be provided manually as part of the Keyword’s configuration or, in Java and .NET, automatically populated based on the “schema” attribute of the Keyword annotation:

	@Keyword(name = "keywordName", schema = "{ 'properties': { 'myInputKey': {  'type': 'string'}}, 'required' : ['myInputKey']}")
	public void myKeyword() throws Exception {
		[...]
	}

[Keyword(name = "keywordName",schema = @" { 'properties': { 'myInputKey': {  'type': 'string'}}, 'required' : ['myInputKey']}")]
        public void MyKeyword()
    {
            [...]
    }

  Unsupported as of 3.11.0

Properties

Required properties

Keywords may require that certain properties, which are not related to business inputs, be made available to them. These properties can originate from the local agent’s configuration, from the controller’s central configuration or even from a dynamic parameter set in the plan or the central parameter view.

Users can provide a list of such required properties as part of the Keyword annotation in Java and .NET:

	@Keyword(name = "keywordName", properties = {"myProperty"})
	public void myKeyword() throws Exception {
		[...]
	}

[Keyword(name = "keywordName", properties = new String[] { "myProperty" })]
        public void MyKeyword()
    {
            [...]
    }

  Unsupported as of 3.11.0

Enable validation

Please note that those properties will be only checked if below properties are set to true in your “step.properties” file. Respectively for java and .net keywords:

• plugins.java.validate.properties=true
• plugins.dotnet.validate.properties=true

When enabled, the keyword execution will fail if any of the defined properties is missing.

Remark: enabling validation is only possible if your Keywords use the step api version 1.1.0 or above.

Optional properties

In case you want to use the validation of properties and still want to have access to optional properties, you can define them separately with following annotation:

	@Keyword(name = "keywordName", optionalProperties= {"optionalProp","optionalProp2"})
	public void myKeyword() throws Exception {
		[...]
	}

[Keyword(name = "keywordName", optionalProperties = new String[] { "optionalProp" })]
        public void MyKeyword()
    {
            [...]
    }

  Unsupported as of 3.11.0

Using dynamic properties

You may also want to validate properties that we call dynamic properties, i.e. properties depending on other properties.

Example:

app.user.name=myName
app.user.myName.pwd=myPwd

You can define them in the required properties annotation with a placeholder as follows:

"app.user.{app.user.name}.pwd"