# Plugin Setup

## ALM-side

The goal of the ALM-side installation is to allow the user to invoke Step from ALM. In order to do that, a custom script has to be created and new buttons added on the TestSet and TestLab screen.

### Installation

To configure ALM,

• Go on the "Customize" screen:

• This will open a new screen where you can open the script editor:

• In the editor, go into the "Toolbar Button Editor" tab and select the "TestPlan" command bar. You will be able from here to create a new command called stepRunnerTP and configured as described bellow:

• You can then create in a similar way a new button for the Test Lab:

• Finally, go to the "Script" tab and add the following function (code available below):

• <CONTROLLER_URL> should point to the url of your Step controller (localhost:8080 in the previous example)
• <DOMAIN_NAME> and <PROJECT_NAME> should be set to the proper Domain/Project (DEFAULT/step in the previous example)

Function ActionCanExecute(ActionName)
'Use ActiveModule and ActiveDialogName to get
'the current context.
'On Error Resume Next

'Use the following script to redirect this function to the module specific function:
'Select Case ActiveModule
'  Case "Defects"
'    ActionCanExecute = Defects_ActionCanExecute(ActionName)
'  Case "Test Lab"
'    ActionCanExecute = TestLab_ActionCanExecute(ActionName)
'  Case "Test Plan"
'    ActionCanExecute = TestPlan_ActionCanExecute(ActionName)
'  Case "Requirements"
'    ActionCanExecute = Requirements_ActionCanExecute(ActionName)
'  Case "Management"
'    ActionCanExecute = Management_ActionCanExecute(ActionName)
'  Case "Test Resources"
'    ActionCanExecute = Resources_ActionCanExecute(ActionName)
'    ActionCanExecute = Components_ActionCanExecute(ActionName)
'  Case "Dashboard"
'    ActionCanExecute = Analysis_ActionCanExecute(ActionName)
'  Case "Test Runs"
'    ActionCanExecute = TestRuns_ActionCanExecute(ActionName)
'End Select
ActionCanExecute = True
On Error Resume Next

Dim iURL, objShell
If ActionName="UserDefinedActions.stepRunnerTL" Then
iURL = "http://<CONTROLLER_URL>/#/root/repository?repositoryId=alm&mode=testset&id=" +Cstr(TestSet_Fields.Field("CY_CYCLE_ID").Value)+ "&qcDomain=<DOMAIN_NAME>&qcProject=<PROJECT_NAME>&qcProfileID=prod"

set objShell = CreateObject("Shell.Application")
objShell.ShellExecute "C:\Program Files\Internet Explorer\iexplore.exe", iURL, "", "", 1
End If
If ActionName="UserDefinedActions.stepRunnerTP" Then
iURL = "http://<CONTROLLER_URL>/#/root/repository?repositoryId=alm&mode=testplan&id=" +Cstr(Test_Fields.Field("TS_TEST_ID").Value)+ "&qcDomain=<DOMAIN_NAME>&qcProject=<PROJECT_NAME>&qcProfileID=prod"

set objShell = CreateObject("Shell.Application")
objShell.ShellExecute "C:\Program Files\Internet Explorer\iexplore.exe", iURL, "", "", 1
End If

file.Close()
On Error GoTo 0
End Function

### Validation

When this has been done, the installation can be validated:

• Connect on your project and go to the "Test Plan" tab. A new "stepRunnerTP" button should be available

• Create the following demo test, using basic logic blocks that can be used with Step for ALM:

• Select it and click on the new "stepRunnerTP" button. A new Internet Explorer with your Step Controller should popup:

• Log into the controller, you should get the following error. This is normal as the Step Controller has yet to know how to communicate to the ALM instance:

• You can then do the same validation on the "Test Lab" tab. The button will be called stepRunnerTL:

## Controller

The second step of the installation is to configure the controller so it will be able to communicate with ALM in order to retreive the tests from ALM and publish the results of the test runs back into ALM.

### Installation

#### Plugin installation

First, you will need to register the ALM DLLs used for accessing the ALM API. You will need admin right on the Controller.

• Open Internet explorer as an administrator and go to ALM, then click on tool:

• Then go to HP ALM Client Registration:

• Finally, click on Register HP ALM to trigger the registration:

• The following message should appears at the end of the installation:

#### Controller configuration

The following lines must be added to the file ...\step-controller-X.Y.Z\conf\step.properties. Please note that almrepository.daemon.javapath should be a 32 bits JRE.

almrepository.daemon.javapath=C:\\Program Files (x86)\\Java\\jre1.8.0_161\\bin\\java.exe

almrepository.daemon.calltimeout=1200000

almrepository.profile.prod.url=http://<ip>/qcbin/

almrepository.profile.prod.user=<user>

almrepository.bdd.parsers=step.repositories.parser.annotated.DefaultDescriptionStepParser,step.repositories.parser.CustomExpectedStepParser,step.repositories.parser.CustomDescriptionStepParser

Also make sure to set an absolute path to the following variable, instead of the default relative attachments folder value:

resources.dir=C:\\path\\to\\attachments

### Validation

We can now validate that the Controller and ALM are able to communicate:

• You can try to execute again from the test lab (so that we can also check the reporting of the execution back to ALM) the small demo test created before:

• Contrary to previously, the controller is now able to query ALM about test information and you should be able to start the execution from the controller GUI:

• You should then be able to see in Step  the result of the execution: (Note that we still have a technical error due to the fact that we execute a non-existing Groovy macro. This point will be addressed in the next section.)

• If you go back to ALM, you should now see the summary of this execution in the "Execution Grid" of the "Test Lab" (a refresh of the view may be needed):

• And also the execution details in the "Test Runs":

## Groovy macros

It is possible to define new Groovy macros that can be called in your test description.

### Installation

In order to use Groovy macros, three steps have to be done:

• First, you have to create a folder on the controller. This folder will contain the Groovy file defining your macros.
• The startup script should be modified by adding the new folder in the class path:

"%JAVA_PATH%java.exe" %JAVA_OPTS% -cp "..\lib\*;..\templates" step.controller.ControllerServer -config=../conf/step.properties

• A new line has to be added in the step.properties file. This option will allow you to specify the name of the Groovy class containing your marcos:

tec.expressions.scriptbaseclass=Templates

When these changes are done, you can then create your macros file in the new folder.

Note that:

• The controller has to be restarted each time you modify these options or the macro file
• The base name of macro file should have the same name used in tec.expressions.scriptbaseclass and have the .groovy extention (...\step-controller-X.Y.Z\templates\Templates.groovy in our example)

### Validation

• In order to validate our groovy macro, we will download the following file and save it under ...\step-controller-X.Y.Z\templates\Templates.groovy: Template.groovy
• You should now restart your controller for the new macro to be taken into account
• You can now re-run the example test case. The function now() should be know and return the current date:

• As a final check, you can also ensure that the new test status is properly reflected in ALM:

#### Troubleshooting

The following exceptions can be faced when using Groovy Macros:

Script1.groovy: 1: unable to resolve class WrongTemplate:

• The name in tec.expressions.scriptbaseclass didn't match the name of your Groovy class
• The name of the folder didn't match the name in the Java path

groovy.lang.MissingMethodException: No signature of method: Script1.unknowMethod():

• The method name is mispelled
• Or our didn't restart your controller after defining the new macros

# Plugin Usage

## Step name

The field "Step Name" of the ALM Test Plan is used to described your steps. It is used in both the test execution reports in STEP and in the Test Runs reports in ALM. It is therefore a good practice to use short and expressive step names

## Description field

The field "Description" of the ALM Test Plan is used to specify the flow of your Test Plan. For the simplest Test Plans it is a simple sequence of keywords with key-values as parameters. More complex Test Plans make use of the STEP Controls in there.

### Keywords

The STEP Keywords may be called using the following syntax:
KeywordName ParameterName1="Parameter value 1" ParameterName2="Parameter value 2" ...

### Controls

The following STEP Controls can be used in an ALM Testplan

#### Set (Variable assignment)

The Set-Control declares a variable and assigns it a value which can then be accessed throughout the Test Plan and sub Test Plans.

Syntax: Set VariableName = "Variable Value"

Multiple variables can be declared and initialized using following syntax:

Set Var1="a" Var2="b" Var3="c"

#### If

The If-Control allows you to execute a sequence of steps only if a particular test evaluates to true.

Syntax: If groovyExpressionThatReturnsTrueOrFalse

The condition "groovyExpressionThatReturnsTrueOrFalse" which is evaluated at execution has to be formulated using Groovy [[1]] and should return true or false.

The If-Block has to be closed using a step End. The list of steps between the If and End steps will be only executed if the conditions returns true.

Example:

Step NameDescriptionExpected Result
Step 1If myVar == "My Value"
Step 2Echo "Entering If sequence..."
Step 3End

#### Echo

The Echo-Control allows you to print a text during execution and can be used for debug purposes. Echo "This is a debug message"

#### Sleep

The Sleep-Control allows you to pause the execution of the current plan for the specified duration.

Syntax: Sleep duration unit

• duration = an integer specifying the duration of the pause
• unit = the unit used to specify the sleep duration. Can be ms,s,m or h

Example:

Step NameDescriptionExpected Result
Step 1Keyword1
Step 2Sleep 10s
Step 3Keyword 2

#### For

The For-Control provides a way to iterate over a range of values. For 1 to 10

The For-Block has to be closed using a step End. The list of steps between the For and End steps will be executed x times.

Example:

Step NameDescriptionExpected Result
Step 1For 1 to 10
Step 2Keyword1
Step 3End

#### For each row in

This "for" syntax will be deprecated in futur releases.

The "For each row in ..." allows to iterate over a specific data source.

Example:

Step NameDescriptionExpected Result
Step 1For each row in excel "C:\tmp\test.xlsx"
Step 2Keyword1 row
Step 3End

#### For each row in attached

This "for" syntax will be deprecated in futur releases.

The "For each row in attached ..." allows to iterate over a data source directly attached to the ALM test or step.

Example:

Step NameDescriptionExpected Result
Step 1For each row in attached excel
Step 2Keyword1 row
Step 3End

#### ForEach

The ForEach-Control allows you to iterate over various datasource types.

Syntax: ForEach SourceType="excel" File="C:/path/to/my/Excel.xlsx" RowHandle="row" Threads=1

• SourceType = the type of the data source. Supported types are: excel, csv, file, folder
• File = the path to the data source. The path has to be accessible to the controller
• RowHandle = the name of the handle (variable) under which the Row object is accessible inside the ForEach
• Threads = the number of threads that process the DataSource. Setting Threads = 1 means that the DataSource will be processed sequentially

Example:

Step NameDescriptionExpected Result
Step 1

ForEach

SourceType="excel"

File="C:/path/to/my/Excel.xlsx"

RowHandle="row"

Step 2Echo row.Column1
Step 3End

#### Sequence

The Sequence-Control allows you to run a group of Controls/Keywords and control the behaviour in case of an error within this group.

Syntax: Sequence ContinueOnError = true

• ContinueOnError = defines if the Sequence execution has to continue after if an error occurs in one of the elements of the Sequence

Example:

Step NameDescriptionExpected Result
Step 1

Sequence ContinueOnError = true

Step 2Echo "Step 1"
Step 3Script ERROR
Step 4Echo "Step 2"
Step 5End

#### Session

The Session-Control ensures that a group of Keywords will be executed on the same Agent token.

Syntax: Session AgentAttribute1 = "MyAgentAttributeValue1" AgentAttribute2 = "MyAgentAttributeValue2"

• You can optionally specify a list of Key-Values that will be used to select the Agent Token on which the Keywords have to be executed

Example:

Step NameDescriptionExpected Result
Step 1

Session

Step 2MyKeyword1
Step 3MyKeyword2
Step 4End

#### Group on

The Control "Group on" has been replaced by the control "Session" as of the version 3.7 and is now deprecated. It might be removed in further releases.

### Variables

Variables that have been declared using the Set-Control or in Parameters.js can be used at different places in the test plan.

#### In the Keyword parameters

Variables can be used in the keyword parameters:

Step NameDescriptionExpected Result
Step 1Set myVar = "Paul"
Step 2Keyword1 Parameter1 = "${myVar}" Step 3Set myVar2 = "happy" Step 4Keyword1 Parameter1 = "Hi, I am${myVar} and I am ${myVar2}" #### Using the output of a keyword in following keywords It is often needed to use the output of a keyword as input (parameter) of the following keywords. This can be achieved using the reserved statement previous Example: Let's say that you have a keyword CreateUser that returns the output parameter "UserID". You might wan't to search for this newly created user using the UserID returned previously. Step NameDescriptionExpected Result Step 1Set Name = "Dupond" Step 2CreateUser Firstname="Paul" Name="${Name}"
Step 3SearchUser ByID="${previous.UserID}" If you have to use this UserID at many places of your test plan it might be better to save its content to a variable and reuse it later: Step NameDescriptionExpected Result Step 1Set Name = "Dupond" Step 2CreateUser Firstname="Paul" Name="${Name}"
Step 3Set UserID="${previous.UseID}" Step 3SearchUser ByID="${UserID}"
Step 4UpdateUser ID="${UserID}" NewName="Dupont" Step 5... ### Expressions In addition to variables and placeholders you have the possibility to use groovy expressions in the keyword parameters. Please refer to http://groovy-lang.org for details about the groovy syntax. Example 1: Simple Addition Step NameDescriptionExpected Result Step 1Set myVar1 = 1 Step 2Set myVar2 = 2 Step 2Keyword1 Parameter1 = "${myVar1 + myVar2}"

This would call the Keyword1 with Parameter1 = "3"

Example 2: Date calculation

Step NameDescriptionExpected Result
Step 1Keyword1 Parameter1 = "${(new Date()+1).format('dd.MM.yyyy')}" This would call the Keyword1 with Parameter1 set to the date of the following day formatted as dd.MM.yyyy ### Placeholders In order to write concise and readable test cases or to hide the complexity of groovy expressions you can define so called placeholders. Like variable and expressions placeholders can be used in the keyword parameters or in checks. Example: Step NameDescriptionExpected Result Step 1 (date)Keyword1 Parameter1 = "Today is the${heute()}"
Step 2 (using the current date time)Keyword1 Parameter1 = "It is currently ${jetzt()}" Step 3 (genereting an unique name)Keyword1 Parameter1 = "Paul Dupont${uid()}"

#### Available placeholders

Per default STEP Enterprise ships with a set of predefined placeholders. For historical reasons these placeholders are in german. In future releases these placeholders will be translated in english.

 Placeholder Description Example uid() Unique ID made of 5 letters aHjKn heute() Current date formatted as dd.MM.yyyy 01.02.2018 heute('dd/MM/yyyy') Current date in a custom format 01/02/2018 jetzt() Current date time formatted as dd.MM.yyyy hh:mm:ss 01.01.2018 10:02:30 datum('DD+1.MM.YYYY-1') Performs a date calculation if the current date is 01.02.2018datum('DD+1.MM.YYYY-1')would return 02.02.2017

#### Custom placeholders

The placeholders are defined in the file Templates.groovy located in the classpath of the controller. You can define custom placeholders directly in this file or in a separate groovy file.

If you define your placeholders in a separated file you have to ensure that the name of the groovy class containing your placeholders matches the property tec.expressions.scriptbaseclass in step.properties

## Expected Result field

### Checks

The Expected Result field can be used to express checks after a keyword execution

Syntax: keywordOutputValue operator "expectedValue"

• keywordOutputValue = the name of the output value of the keyword to be checked
• operator = The operator to be used to perform the check. The following operators are supported:
• = equality check
• ~ regular expression check
• contains
• beginsWith
• endsWith
• expectedValue the expected value

Example:

Step NameDescriptionExpected Result
Step 1Keyword1
Parameter1 = "Value1"
Parameter2 = "Value2"
OutputParameter1 = "MyExpectedValue"
OutputParameter2 beginsWith = "MyExpected"

### Set (Variable assignment)

The Expected Result field can also be used to assign the output parameters of a keyword to variables in order to make them accessible to following steps.

This can be achieved using the reserved statement output

Syntax: Set VariableName = "${output.MyKeywordOutputParameter1}" Example: Let's say that you have a keyword CreateUser that returns the output parameter "UserID". You might wan't to assign the content of the output parameter "UserID" to a variable and use this variable in the following steps of your Testcase. Step NameDescriptionExpected Result Step 1Set Name = "Dupond" Step 2CreateUser Firstname="Paul" Name="${Name}"Set MyUserID = "${output.UserID}" Step 3SearchUser ByID="${MyUserID}"
Step 4DeletUser ID="\${MyUserID}"
Tags:
Created by Jerome Brongniart on 2019/03/11 13:44