Keywords
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 a Java virtual machine and will be executed on Java agents. Thanks to Java’s ScriptEngine, you can write keywords in Java, JavaScript or Groovy (hence the generic name Script).
- NodeJS: These keywords will be NodeJS functions and will be executed on NodeJS agents.
- .Net: These keywords have to be C# based functions and will be executed on .NET agents. This type of keyword needs an enterprise license.
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 his 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 of the step plugins and allow to integrate 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 a Oryon keyword.
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.
Registering a Keyword
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 type:
- 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).
- Type The type of the keyword. Changing the type will also change the type specific fields (indicated in red in the screenshot).
- Schema The JSON schema allowing to validate the inputs. With this field you can specify the name of your keyword inputs, their type, 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.
- We use in this example the step.plugins.java.GeneralScriptFunction keyword type. You will find the list of available types 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 allowing you to directly drop the file via the GUI, lookup and update existing resources and download back your files.
For .NET, the only needed field is the DLL library containing the keyword to call
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:
- PDF Test: Needs a scenario file (leave empty for creating a new scenario)
- SoapUI: Needs a SoapUI project file and the name of the Testsuite/Testcase
- JMeter: Needs a JMeter Testplan
- QF-Test: Needs a QF-Test testsuite, the procedure and a boolean indicating if the suite should be send to the agent
- Oryon: Needs the script language and the script file
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
- PDF Test: See step.plugins.pdftest.PdfTestFunction
- SoapUI: See step.plugins.soapui.SoapUIFunction
- JMeter: See step.plugins.jmeter.JMeterFunction
- QF-Test: See step.plugins.qftest.QFTestFunction
- Oryon: Needs the script language and the script file. See step.plugins.oryon.OryonFunction