Categories: USER GUIDE KEYWORDS KEYWORDS DEPLOYMENT

Deployment

You can add and manage Keyword by manual registration or automatically using package file. In this guide, we will first discuss ways of adding Keywords via package file. For description about the manual way of adding Keywords, please see the section: Adding a new Keyword by manual registration.

Adding Keywords via package file

With package files you can add and manage Keywords in bulk. They are the most efficient way to add and manage Keywords at scale. The two main benefits adding Keywords via package file areas follows.

Autodiscovery: The main idea is that Step will automatically discover Keywords and create entries for every keyword found in the package. Step parses 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.

Bulk operation: Through resource mapping, each Keywords are bound to a JAR resource (for Java), or a DLL resource (for .NET). All Keywords added from the same package file are mapped to the same package so that it is possible to manage a set of Keywords via the same package file.

How to add Keywords via upload package

Adding Keywords from a package requires uploading a resource file, such as a JAR or DLL file, or a Maven snippet from a repository artifact. To add Keywords, navigate to the Keywords collection window to add Keywords by using resource file or by using Maven snippet.

Using a resource file to add Keywords

To upload a resource file or add a Maven snippet, click Upload package in the keyword view to display the New Keyword Package dialog.

Screenshot of how to upload keyword package

You can then select your resource file or directly drag it into the Package file field.

Under the Found Keywords panel, on the New Keyword Package dialog, Step displays the list of Keywords found in the package file:

Screenshot of keywords found in keyword package

After clicking save on the dialog, your new Keywords will appear in the Keywords view, and the Package column shows the package they are bound to.

Using Maven snippet to add Keywords

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

On the New Keyword Package dialog, paste the snippet in the Package file field and wait for the keywords to be loaded.

How to create versions of the same Keyword

To maintain multiple versions of the same package, add a new parameter to the keyword screen template.

The new Version parameter will appear in the New Keyword Package dialog and will let you distinguish multiple versions of the same keyword:

Routing Keyword

When configuring your Keyword package, you have the possibility to define the following routing rules for all Keywords managed by the package:

The following settings lets you specify how to route the Keywords of a package.

  • Execute on controller: executes all Keywords directly on the controller rather than on agents
  • Agent token selection criteria: A list of agent attributes that grants Keywords access to perform basic Keyword routing, restricting the set of agents that can execute this Keyword to the ones with the specified attributes.

How to manage versions of a Keyword

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.

The 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: 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 env==TEST, and the version 1.0.0 if you execute it with env==PROD.

How to update a Keyword package

From the Keyword window, hold the pointer over the package name of any Keyword entry then click the pen icon (Edit package):

In the Edit Keyword Package that appears, you can then drag your package file onto the Package file field then click Save. Step will automatically update the revision of the resource and all the associated Keywords.

How to delete 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:

Adding a new Keyword by manual registration

In order to use your Keywords with Step, you need to register them. This can be done through the web interface or the Java API.

Generic fields

    From the Keyword collection window, use the + button to open the following New keyword dialog. The dialog is a visial editor that lets you fill in generic and type specific information for your Keyword.

    The following fields are generic to all Keyword types:

    • Name: The name of the Keyword let’s you reference the Keyword. For Java (resp. C#), this field must match the name given in the annotation (resp. the attribute).

    • Description: The description filed of the Keyword lets you put more details / explanation about the Keyword in a free text field.

    • Schema: JSON schema used to defined keywords’input in the plan editor and for validation at execution time. With this field you can specify the name of your Keyword inputs, their types, whether they are mandatory and their default values. The schema editor let you construct you schema seamlessly (4).

    • Type: The type of the Keyword. The type specific fields (indicated in the screenshot in red) vary for each type.

    • Keyword type’s fields : each keyword type has its specific configuration fields

    • Advanced configuration:

      • Call timeout (ms): The maximum duration (in milliseconds) of a Keyword execution. If the Keyword execution last for more than this timeout, the controller will report an error and the agent will try to interrupt the Keyword.
      • For Execute on controller and Agent token selection criteria: See Routing 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. Please note that in the following example,:

    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 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:

      • Script language: The language used (Java, JavaScript or Groovy)
      • Libraries: An optional library, containing the Keyword dependencies.
      • JAR file: The script/JAR file containing the Keyword.

      Note: The file selector lets you 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 (that is, other DLL files as well as PDB files) can be provided in the Libraries field, and you can drag the Keyword’s own DLL file 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. The folder must contain a sub-folder named keywords, containing a keywords.js file. You can specify the folder as a path accessible from the controller or as a zip file that you can drop on the GUI. Take a 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:

      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"));
      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"));
      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 required fields are Name and Type.

        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:

        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

        The following is a 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

          Find usage of Keywords

          This feature is not limited to Keywords and can be used similarly for plans and resources. The functionality allows searching for references from plans and composite Keywords to the selected element, facilitating efficient usage across your automation project.

          How to

          Note: only the Plans and composite Keywords which are directly accessible in the current project are displayed as link.

          See Also