Adding and Configuring New Agents

Step’s architecture allows for the dynamic registration of agents. It is designed to handle hundreds of agents, enabling the execution of keywords at a high rate. Different types of agents have been released in order to support tight integration with different runtimes. For example, DLL-based keywords can run on the .NET agent, while a Node.js project can be executed on Step’s node agent.

Step’s default routing will guarantee a natural affinity between a keyword’s given type and the agent on which this keyword’s execution will occur. However, users can define arbitrary affinity patterns allowing for further customization. For example, one may decide to assign a specific set of agents to a group that will work in isolation from the other agents, depending on contextual information provided at runtime.

In this tutorial, we will cover the configuration of an agent and how to design groups based on affinity patterns. We will also look at the different options users have to design and implement complex keyword routing rules.

‍Configuration file

All of Step’s agents use the same type configuration file - AgentConf.json - which should look similar to this by default:

  {
"gridHost":"http://localhost:8081",
"registrationPeriod":1000,
"workingDir":"../work",
"tokenGroups":[
{"capacity":10, 
"tokenConf":{
	"attributes":{ "myAffinityCriterion1" : "myAffinityValue1"},
  "properties": {
    "myProp1": "myValue1"
  }}
}
],
"properties":{
	"myProp1":"myDefaultValue",
	"myProp2":"myValue2",
	"plugins.jmeter.home":"../ext/lib/jmeter",
	"plugins.selenium.libs.2.x":"../ext/lib/selenium/selenium-2.53.1",
	"plugins.selenium.libs.3.x":"../ext/lib/selenium/selenium-java-3.0.1"}
}
  Copy

You are probably already familiar with the gridHost parameter, which allows the agent to connect and register against a controller.

The tokenGroups parameter exposes a collection of pools that can be tagged with different key-values (via the properties sub-map).

• The sub-map, called attributes, can be used to tag a certain pool with key-values and allows for a distinction between this pool and other pools belonging to the same agent, or to other agents from the same technical type.
• The sub-map called properties allows users to set specific property values which will only be visible in the context of a token originating from this pool.
• This means that keywords may “see” different property values depending on which token they end up being executed on.

The capacity parameter determines how many “tokens” (i.e keyword execution slots) will be made available in the corresponding pool upon starting the agent.

Note Not to enable more tokens than the underlying host is capable of servicing based on its allocated infrastructure resources (CPU, Mem, I/O…).

Lastly, a separate properties map allows the declaration of global agent properties which are made accessible to keywords and will look the same to every keyword executing on the agent, assuming the property is not overridden within the property map of the pool.

Token Pool Attributes

In the sample file provided above, the attribute “myAffinityCriterion1” is set on the only pool which has been configured, and the value “myAffinityValue1” has been assigned to it. This means that keywords may or may not be routed to this token pool depending on selection criteria which will be evaluated at runtime.

These criteria can be decided either by setting the corresponding variable in the plan, in the Routing map of a CallKeyword instance or of a Session instance, or via the route_to_XYZ variable, which can itself be set as a parameter and be manipulated dynamically.

Token Pool properties

In the sample file provided above, the dummy property “myProp1” is set on the only pool which has been configured, and it takes the value “myValue1”. This means that keywords running in the context of tokens belonging to this pool will see this value when accessing the property:

  properties.get("myProp1");
// myValue1
  Copy

Routing examples

Assuming that in the following examples we have installed and started two agent pools (which may or may not be running on the same agent and/or host) using the attribute “myAffinityCriterion1” as a distinguishing criterion. Values “myAffinityValue1” and “myAffinityValue2” have been assigned respectively to token pools 1 & 2.

Explicit keyword routing

Both the CallKeyword (i.e the underlying object created when using a keyword in a plan) and Session artifacts showcase a section called “Keyword routing”. This section exposes a map of desired attributes which will be matched at runtime against the actual attributes of the tokens available for selection.

If we set our criterion “myAffinityCriterion1” to the value “myAffinityValue2”, then this keyword’s execution will only be able to take place on the corresponding pool and agent:

Upon execution, the details pane confirms this. If you look at the url of the agent taking care of the execution, you will see that it is the url of agent 2, as expected:

Implicit routing

The same result can be achieved using the reserved variable routeto. This variable can be set as a central parameter and overridden in a plan where necessary.

After removing the explicit routing key and value from our keyword call, we’ll apply a similar constraint with the routeto variable by appending the criterion to its name and setting the value as a parameter value.

Reminder, the execution will take place on agent 2

Let’s now override this value from within the plan by using a set artifact from within the plan, just before the keyword is effectively called.

This time, the execution took place on agent 1.

Summary: This article details the configuration of an agent, as well as how to design groups based on affinity patterns; it also lists the different options users have to design and implement complex keyword routing rules.