One of the features of Agilitest is the ability to use subscripts. This will allow you to factorize the common functions of your tests. Agilitest also allows you to pass values as parameters to your subscripts and thus make your subscripts scalable and generic.
A subscript created from a script will always perform the actions it is composed of with the same parameters.
It is also possible to modify the values of the subscript to use it in several possible configurations.
There are different ways to pass parameters to a subscript:
- Manually, by entering the parameters in the script
- or with a dataset, using a CSV/JSON file
▶️ You can find a 3 part tutorial about passing parameters to a subscript on our Youtube channel : Part 1, Part 2, Part 3
Add parameters to a susbcript
If you don't have a subscript call action in your script, you can create one in two ways:
- Either by entering the name of the subscript in the action
To do that, click on the “subscript” action in the action menu
.png)
Click on the action “Call the script [ ]” to enter information
.png)
Then, enter the name of the script you want to call as a subscript.
.png)
2. Either by dragging a script into your test
From the project explorer, click on a script you want to use as a subscript and drag it into your script.
.png)
This will create a “Call the script” action with the dragged script.
.png)
1. Parameters entered manually
It is possible to pass parameters manually.
Once you have created the sub-script call action in your script, you can pass parameters manually to your sub-script, directly from your script.
To do this, click on the call sub-script action, "Call the script [scirpt_name]”
.png)
Then click on “add parameter”
.png)
For information, the first parameter will always be named "Parameter 0", then the second parameter will correspond to "Parameter 1", the third parameter to "Parameter 2", etc…
.png)
Once you have entered the parameters in the script, you need to add them in the subscript.
To do this, open your subscript from the project explorer.
.png)
From your subscript, click on the action that will execute the settings and then open the special values view.
Select "Script parameter" from the special values and choose the parameter you are interested in.
%20(1).png)
When the action of calling a subscript is executed, it will execute the specified parameters.
📙 To know more
With the call script action, a script will call a subscript. When the script has parameters defined, the subscript will retrieve them and pass them to $param(x) (see the scheme above "Passing parameters to a subscript from a script”)
During the execution, the parameters will be shown in a pop-up at the bottom to the right on the editor.
.png)
For your information, to make the pop-up indicating the settings reappear, you can click on the "\x" button.
.png)
When the parameters are entered manually, the execution of your parameters will be done only once. To multiply the iterations, you will have to create as many subscript call actions as the number of iterations you want. In other words, you will have to repeat the previous steps for each new iteration.
💡 Tip
Add comments to your parameters to track data and to tag the parameters. Those comments will be visible in the execution report.
2. Parameters entered from a JSON/CSV file
Create a JSON/CSV file
It is also possible to pass parameters from a JSON/CSV file. A JSON/CSV file corresponds to a dataset. The dataset will allow to create iterations. The behavior of the subscript on a dataset will be to loop the number of iterations contained in the dataset.
Unlike a manual input, where you would have had to create the subscript call action several times and enter parameters each time, for the dataset, the parameters will be organized in a table that will be used by a single subscript call action.
There are two ways to create a JSON/CSV file:
- Click on “New component” situated at the top ion the left of the Agilitest editor
.png)
Then select “Create a CSV file” or “Create a JSON file”
.png)
2. In the project explorer, open the “data files” view
.png)
Finally, click on a button tocreate a JSON or CSV file
.png)
Once the CSV/JSON file is created, it can be used from the call script action.
To associate your JSON/CSV file to your script, click on the call script action “Call the script [name_of_script]”
Select “CSV/JSON” file
There are two ways to add your CSV/JSON file in the action:
- Directly from the project explorer
Drag your CSV/JSON file from the project explorer to the call the script action.
.png)
2. By selecting the file from Windows explorer
Click on the file icon to search your file from Windows explorer
%20(1).png)
Once the CSV/JSON file is added to the subscript call action, it will automatically open during the execution of your test.
CSV/JSON files are in the form of a table.
.png)
They are both used in the same way with the only difference that it is possible to rename the column hearders in a JSON file.
.png)
In the table, you can add columns that correspond to the parameters, as well as rows that correspond to the iterations by clicking on the assigned buttons.
.png)
With a CSV/JSON file, the subscript is executed as many times as there are iterations.
Once your file is completed, you can recover the variable of your subscript by using the $param(…) function and by passing the value of the parameter column you are interested in.
Example :
Enter $param(0) in the action to return the value of the first column in your CSV/JSON file.
.png)
📙 To know more
The parameters of the subscript are defined from a CSV (comma-separated values) file consisting of an array with rows and columns. Depending on the number of rows, this determines the number of times the file will be called, this is called iterations. (See the scheme above "Passing parameters to a subscript with a csv file")
The same goes for the parameters of the subscript defined from a JSON (JavaScript Object Notation) file composed of an array with rows and columns. Depending on the number of rows, this determines the number of times the file will be called, this is called iterations. (see the scheme above "Passing parameters to a subscript with a json file")
For a complex JSON file, it is composed of an array with rows and columns like a classical JSON file. Only, the iterations are done according to the number of values in a line. The number of values in a line corresponds to the number of parameters (See the scheme above "Passing parameters to a subscript with a complex json file").
Parameters can be created from an http file or a database from a web page. The principle is the same as for a JSON/CSV file, the iterations correspond to the number of lines and the parameters to the number of columns (see the scheme above "Passing parameters to a subscript with a http file").
CSV/JSON file execution options
Once the dataset is created, you can add options on the execution of your CSV/JSON files. By default, the iterations are done according to the order presented in the table, but it is possible to ask Agilitest to make the execution of your iterations random.
To do that, click on your element and check the box “Use random row”
You can also give a "Range of indexes", which allows you to limit the number of iterations among the total iterations that make up the JSON or CSV file.
If you want, with this option you can also execute only one precise row by indicating its number.
Example: If your JSON file consists of 150 iterations, you can specify 0-50 in the index range to limit the execution to the first 50 iterations.
Finally you have the option "Execute as suite" so that the execution continues until the end even if an iteration is in error.
When you encounter an error in one of the iterations, this will cause your test to be in error, and thus stop the test considering it as KO. This option allows you to consider each iteration as an independent test.
Example: On an execution of 50 iterations, if the 48th iteration encounters an error, it will be indicated as being in error but will not prevent going to the 49th and so on.
🔸 Warning
Actions created after the call script action is executed as a suite are not saved and will not appear in reports.
3. Parameters from an interface element
It is possible to make only one element of your parameters appear. In a complete subscript, if one of the actions does not have an element then the param(0) will be used by default. To fill in the param(0) that will be used, you can add a "Element’s text" to the action that calls the subscript.
From the call script action, click on "Element’s text".
Then add an element selected with the capture tool.
.png)
When you execute your subscript, it will display the element you have captured.
This is especially useful when you are looking for data in your table among a set of rows. Agilitest will allow you to iterate until you arrive at the line you were looking for and allows you to take a specific action on this line.
Example: You have a table that contains 5 different rows. By giving the component "table" as input to the subscript, Agilitest will loop through the rows of the table in the subscript.
📙 To know more
Parameters can also be taken from elements. For a list of elements (DIV), each element corresponds to an iteration and each separate value of a text property "\n" corresponds to a parameter. (See the scheme above "Passing parameters to a subscript with a list of elements (div)”)
For a complex list of elements (Rows), each row corresponds to an iteration and each separate value of a divided text "\t" corresponds to a parameter. (see the scheme above "Passing parameters to a subscript with a list of complex elements (rows)”)
For a list of special elements, each of its elements has sub-elements which themselves have values. The number of iterations is determined by the number of sub-elements and the number of parameters is determined by the separate text property values that make up these sub-elements. (See the scheme above "Passing parameters to a subscript with a list of special elements”)
Parameter execution options
Iterations
Adding iterations will allow your script to be executed multiple times. This is handy when you have a function that can be used successively and will allow you to check your UI behaviors.
Example: The "go back" function to return to previous pages of a web page that can often be repeated several times.
To add iterations to a subscript composed of parameters, click on your subscript call and increase the number of iterations.
.png)
Example: If you add 3 iterations, the subscript and its parameters will be executed 3 times.
Adding iterations allows you to avoid flaky tests, i.e. actions that are executed several times and that will sometimes produce an error for no particular reason.
Iterations, conditions and variables are not always usable depending on the case :
- Executing the subscript from the parameters added from your script will give you access to all available options: iterations, variables and conditions.
- Executing the subscript from a JSON or CSV file will not allow you to use variables or iterations but will allow you to add conditions.
- Executing the subscript with adding the text of an element will allow you to add iterations and conditions but will not give you access to variables.
Return value
It is possible to get data from a subscript. This will create a dynamic (non-modifiable) variable since the return variable will automatically value the variable of the main script.
There are two ways to obtain a returned value:
1. Create a variable
At the very bottom of the subscript is a small yellow arrow allowing you to add a return value.
Once the return variable has been created, it must be retrieved from the script call action.
To do this, click on the "Variables" button to tag it in the main script with an equivalent variable opposite.
.png)
2. Property variable
Create a property action to get data from the interface.
To do that, click on “Property” in the action menu
The property action will target an interface element.
For that, click on the “Load” button in the property action
%20(1).png)
It will load all the properties that are associated with this element.
Click on the property you are interested in to have it loaded during the execution.
.png)
These properties correspond to the attributes of the element that are found in the "Captured Element's Parents" window when the element is captured.
ATS properties also appear in the list of properties as well as formatting elements (CSS).
When a property is selected, it will be placed in a variable that will take the value of the selected property.
.png)
Example: If you select the property "text" with the value "Hello world - Wikipedia" in the list of captured properties.
.png)
Once the value is created from the property, you can return it.
Click on the "Add a return value" button
.png)
Then, open the special values menu and select in the script variables the one that corresponds to the property variable
%20(1).png)
Click on the sub-script call action, then on "Variables" to specify that a value is returned from the subscript.
.png)
Select the variable that will store this return value from one already created or you can also create a new one.
.png)
This means that the return value of the sub-script will be retrieved from the variables of the main script.
This allows to pass data between a script and its sub-scripts.
📙 To know more
The main script calls a subscript that contains values. It is possible to pass parameters to this subscript and it is also possible to return the values from the sub-script to the main script. With the return value action, you can call a number of values that will be returned based on the values in the subscript. Sometimes the information sent (parameters or return values) is not expected and therefore not processed.
