Testim Documentation

Welcome to the Testim documentation. You'll find comprehensive guides to help you get started quickly, example code snippets, and tips for being more productive. You will also find details about advanced features that allow you to customize Testim to fit your environment or special testing conditions. Don't worry, we'll support you if you get stuck. Let's jump right in!

Guides    Changelog

Repeat Group Loops

Repeat a group of steps using: while... do... loops & for loops

The Repeat Group Loop feature lets you execute a Group step multiple times according to a set of predefined conditions. A “Loop” must be run on a series of steps which have already been configured as a “group”. To learn more about creating groups, see Groups.

📘

The maximum number of iterations for any loop is 99 iterations.

There are 6 options for when to repeat a group:

  • Don’t repeat – Use this option (default) when you don’t want your group of steps to be repeated.
  • While element – A While element loop enables you to specify whether or not to run the same set of actions/validations depending on whether or not the specified element exists (or does not exist) on the page. The element can be any DOM object, such as property ID, text, or class. See CONFIGURING A “WHILE ELEMENT” LOOP.
  • While element text is – A While element text is loop is similar to the While element loop; however, this loop enables you to specify an expected text value for the specified element. The loop will run only if the specified text exists. See CONFIGURING A “WHILE ELEMENT TEXT IS” LOOP.
  • For each item – A For each item loop (i.e. for each loop) allows you to run the same set of actions/validations on similar elements. This is useful to test a list of repeating elements, like a table with multiple rows. See CONFIGURING A “FOR EACH ITEM” LOOP.
  • Loop for (i.e. for loop) – A Loop for loop (i.e. a for loop) allows you to run the same set of actions/validations a specified number of times. This value can be set to a number or a parameter with a number value. See CONFIGURING A “LOOP FOR” LOOP.
  • Custom – A Custom loop allows you to run the same set of actions/validations depending on a specific value of an element on a page. The loop will run if the value exists. You can enable custom JavaScript code for the condition. See CONFIGURING A “CUSTOM” LOOP.

It is often necessary to keep track of the current iteration you are in while using a loop, for example when iterating through an array. For that purpose, you can use the TESTIM_ITERATOR variable in loops. See USING THE LOOP ITERATOR VARIABLE .

Configuring a “While element” loop

A While element loop enables you to specify whether or not to run the same set of actions/validations depending on whether or not the specified element exists (or does not exist) on the page. The element can be any DOM object, such as property ID, text, or class.

To configure a “While element” loop:

  1. Choose a group step which contains the steps you want to include in the loop.

📘

Group steps can be identified by the Group icon (a picture of a folder) in the upper left-hand corner of the step.

  1. Hover over the group step and then click on the Show Properties () icon. The Group Properties panel opens on the right-hand side.
  1. In the Group Properties panel, click on Repeat group.
  1. Select the While element radio button.
  1. If your AUT (application under test) window is not currently open to the relevant page, you will be prompted with a message to "Open base URL" or "Run test to relevant step". If the condition relates to a step other than the base URL page, click on Run test to relevant step. In this case, you will need to click on the While element radio button again once the AUT is ready.
  2. In the AUT window, hover your mouse on the relevant element and then click on it to select it.
    The selected element is shown in the Target element box in the Repeat group section of the Group Properties panel.
  1. If you would like to view, replace, or adjust the settings for the selected element, use the procedures described in Modifying the Test Using the Properties Panel.
  2. Specify the type of Element condition to apply. Options are:
    • Visible – the step only runs if the element is visible on the page.
    • Not visible – the step runs only if the element is not visible on the page.
  3. If you would like to adjust the settings for how long Testim checks before declaring a condition to be true or false, use the procedure described in Advanced Condition Settings.

The loop is added to the step as indicated by the loop icon shown on the group step tile. Whenever you run this test, the loop process will run. To learn how to view the results of the run, see VIEWING LOOP RUN RESULTS.

Configuring a “While element text is” loop

A While element text is loop is similar to the While element loop; however, this loop enables you to specify an expected text value for the specified element. The loop will run only if the specified text exists.
To configure a “While element text is” loop:

  1. Choose a group step which contains the steps you want to include in the loop.

📘

Group steps can be identified by the Group icon (a picture of a folder) in the upper left-hand corner of the step.

  1. Hover over the group step and then click on the Show Properties () icon. The Group Properties panel opens on the right-hand side.
  1. In the Group Properties panel, click on Repeat group.
  1. Select the While element text is radio button.
  1. If your AUT (application under test) window is not currently open to the relevant page, you will be prompted with a message to "Open base URL" or "Run test to relevant step". If the condition relates to a step other than the base URL page, click on Run test to relevant step. In this case, you will need to click on the While element text is radio button again once the AUT is ready.
  2. In the AUT window, hover your mouse on the relevant element and then click on it to select it.
    The selected element is shown in the Target element box in the Repeat group section of the Group Properties panel.
  1. In the Expected value box, the current value for the selected element is set by default. If you would like to specify a different value, enter the value in the Expected value box. If you would like to set a range of values, enter a Regex expression, a short JS expression, or a parameter.
  1. If you would like to view, replace, or adjust the settings for the selected element, use the procedures described in Modifying the Test Using the Properties Panel.
  2. If you would like to adjust the settings for how long Testim checks before declaring a condition to be true or false, use the procedure described in Advanced Condition Settings.

The loop is added to the step as indicated by the loop icon shown on the group step tile. Whenever you run this test, the loop process will run. To learn how to view the results of the run, see VIEWING LOOP RUN RESULTS.

Configuring a “For each item” loop

A For each item loop (i.e. for each loop) allows you to run the same set of actions/validations on similar elements. This is useful to test a list of repeating elements, like a table with multiple rows.

To configure a “For each item” loop:

  1. Choose a group step which contains the steps you want to include in the loop.

📘

Group steps can be identified by the Group icon (a picture of a folder) in the upper left-hand corner of the step.

  1. Hover over the group step and then click on the Show Properties () icon. The Group Properties panel opens on the right-hand side.
  1. In the Group Properties panel, click on Repeat group.
  1. Select the For each item radio button.
  1. If your AUT (application under test) window is not currently open to the relevant page, you will be prompted with a message to "Open base URL" or "Run test to relevant step". If the condition relates to a step other than the base URL page, click on Run test to relevant step. In this case, you will need to click on the For each item radio button again once the AUT is ready.
  2. In the AUT window, using your mouse, select the first repeating relevant element (for example, the first cell of a table) to select it.
    The selected element is shown in the Target element box in the Group Properties panel, and the Max number of items field opens showing the default value as 99, meaning that this loop will run for up to 99 similar items. If you would like to set a lower limit, you may optionally enter a smaller value for the maximum number of items.
  1. If you would like to view, replace, or adjust the settings for the selected element, use the procedures described in Modifying the Test Using the Properties Panel.
  2. If you would like to adjust the settings for how long Testim checks before declaring a condition to be true or false, use the procedure described in Advanced Condition Settings.

The loop is added to the step as indicated by the loop icon shown on the group step tile. Whenever you run this test, the loop process will run through each of the items similar to the item you selected. To learn how to view the results of the run, see VIEWING LOOP RUN RESULTS.

Try it yourself

Click here to open a sample test which includes a For each item loop. Try running the test and adjusting the loop configuration.

Configuring a “Loop for” Loop

A Loop for loop (i.e. a for loop) allows you to run the same set of actions/validations a specified number of times. This value can be set to a number or a parameter with a number value.

To configure a “Loop for” loop: where the value is a number:

  1. Choose a group step which contains the steps you want to include in the loop.

📘

Group steps can be identified by the Group icon (a picture of a folder) in the upper left-hand corner of the step.

  1. Hover over the group step and then click on the Show Properties () icon. The Group Properties panel opens on the right-hand side.
  1. In the Group Properties panel, click on Repeat group.
  1. Select the Loop for radio button. The Value to loop for field opens.
  1. Enter a value for the number of times you want these steps to be looped through.

📘

The maximum number of iterations allowed is 99.

  1. If you would like to adjust the settings for how long Testim checks before declaring a condition to be true or false, use the procedure described in Advanced Condition Settings.

The loop is added to the step as indicated by the loop icon shown on the group step tile. Whenever you run this test, the loop process will run. To learn how to view the results of the run, see VIEWING LOOP RUN RESULTS.

To configure a “Loop for” loop: where the value is a parameter:

  1. Choose a group step which contains the steps you want to include in the loop.

📘

Group steps can be identified by the Group icon (a picture of a folder).

  1. Hover over the arrow to the left of the group, and click on the + (plus sign) that appears. The Actions tab opens.
  1. Click on Add custom action. The Add Step window opens.
    For more information about adding custom actions, see Creating a Custom Action.
  1. In the Enter a name for the new step field, enter a (meaningful) name for this step.
  2. If this is a shared step (to be made available to reuse in this and other tests), keep the box next to Shared step selected. This is the default. Otherwise, deselect it.
    For more information about shared steps, see Reuse.
  3. Click Create Step.
    The editor opens, and the Custom Action Properties panel opens on the right-hand side.
  1. Enter the appropriate code to pass the parameter you are exporting to the group step. (For example: exportsTest.number = 2;) For more information about exporting parameters, see Exports Parameters.
    Note: The maximum number of iterations allowed is 99.
  2. Optionally edit the properties in the Custom Action Properties panel.
    • Description - Change the description of the step.
    • +PARAMS - Add JavaScript or HTML parameters. For more information, see Parameters in custom JavaScript steps.
    • When this step fails - Specify what should happen if the step has failed.
    • When to run step - Specify when this step should be included in the test. Conditions may include the existence of an element/element text, or a custom JS function.
    • Override timeout - Keep waiting until the refresh occurs even after timeout.
  3. Click the back arrow to return to the main editor window.
  1. Hover over the group step and then click on the Show Properties () icon. The Group Properties panel opens on the right-hand side.
  1. In the Group Properties panel, click on Repeat group.
  1. Select the Loop for radio button. The Value to loop for field opens.
  1. Enter the parameter you used in Step 7 (above). (For example, number).
  2. If you would like to adjust the settings for how long Testim checks before declaring a condition to be true or false, use the procedure described in Advanced Condition Settings.

The loop is added to the step as indicated by the loop icon shown on the group step tile. Whenever you run this test, the loop process will run. To learn how to view the results of the run, see VIEWING LOOP RUN RESULTS.

Try it yourself

Click here to open a sample test which includes a “Loop by Number” for loop and a “Loop by Parameter” for loop. Try running the test and practice adjusting the configuration.

Configuring a “Custom” loop

There are times that you may want to create loops that are based on more than just validating that an element is visible or that specific text exists. You may want to check an element’s value or create more complex conditions. The Custom loop option enables you to do this by creating conditions for your loop defined as JavaScript steps.
For example, if you would like to check the URL in order to identify whether or not you are on the login page, you could use the following custom condition in your loop:

return loginButton.innerText === 'LOG IN';

You can also define HTML or JavaScript parameters and then refer to these parameters in the step. For example, you can select an HTML element such as a button and then create a condition to check the text on that button.

To configure a “Custom" loop:

  1. Choose a group step which contains the steps you want to include in the loop.

📘

Group steps can be identified by the Group icon (a picture of a folder) in the upper left-hand corner of the step.

  1. Hover over the group step and then click on the Show Properties () icon. The Group Properties panel opens on the right-hand side.
  1. In the Group Properties panel, click on Repeat group.
  1. Select the Custom radio button.
  1. The Set condition window opens.
  1. If you would like to use parameters for your custom loop, define the parameters as follows:
    • In the right-hand pane, click the + PARAMS button.
    • JS parameter: If you would like to add a JavaScript parameter, select JS from the dropdown list and type in the JavaScript parameter.
    • HTML parameter: If you would like to define an HTML element as a parameter, select HTML from the dropdown list. The browser opens, displaying the relevant webpage for this step. Do the following:
      • If your AUT (application under test) window is not currently open to the relevant page, you will be prompted with a message to "Open base URL" or "Run test to relevant step". If the condition relates to a step other than the base URL page, click on Run test to relevant step. In this case, you will need to navigate back to the Set condition screen by clicking on Edit next to the Custom option in the Repeat group section of the Group Properties panel, and then clicking + PARAMS followed by HTML. In the AUT window, hover your mouse on the relevant element and then click on it to select it. The selected element is shown in the Target element box in the Properties panel.
  • The selected element is automatically named “element”. To assign a relevant name to the element, click on the edit icon and enter the desired name.
  1. In the function text box, type in the desired JavaScript condition. If you have defined parameters, you can refer to those parameters in your JavaScript condition.

📘

If you are using DOM selectors other than HTML parameters (e.g. jQuery), then empty arrays are truthy, so you need to use $().length instead of $().

  1. If you would like to override the default timeout setting (30000 ms), click on the Override timeout button in the Custom Step Properties pane, and enter the desired timeout limit.
  1. Click the back arrow to return to the main Editor window.
  1. If you would like to adjust the settings for how long Testim checks before declaring a condition to be true or false, use the procedure described in Advanced Condition Settings.

The loop is added to the step as indicated by the loop icon shown on the group step tile. Whenever you run this test, the loop process will run. To learn how to view the results of the run, see VIEWING LOOP RUN RESULTS.

Using the Loop Iterator Variable

TESTIM_ITERATOR is a preconfigured variable that allows you to keep track of and use the value of the current loop iteration. Each time a loop is run, the value of TESTIM_ITERATOR increases by one. The following are some examples of how you can use TESTIM_ITERATOR.

  • Example 1 – using the value of the current loop iteration in a step of a test
  • Example 2 – designate the number of times to repeat a loop by using the value of the current loop iteration in the conditions of a loop step

Example 1

You can use TESTIM_ITERATOR in a step of your test that is within a loop. The value of the current iteration of the loop will be used when the step is run.
The following procedure explains how to use TESTIM_ITERATOR for text validation in a step within a “For each item” loop.

To use the value of the current loop iteration in a step:

  1. Choose a group step which contains the step for which you would like to use the TESTIM_ITERATOR.

📘

Group steps can be identified by the Group icon (a picture of a folder).

  1. Double-click on the group tile to open the group.
  1. Hover over a step where you want to use the iteration value (e.g. text validation), and then click on the Show Properties () icon. The Properties panel opens on the right-hand side.
  1. Edit the properties based on the type of loop you are editing, including the property based on the loop iterator. (See the explanation of configuring loops above.) For example, if you are editing a “For each item” loop, enter “<array_name>[TESTIM_ITERATOR]” in the Expected value field.
  1. Click the back arrow to return to the main Editor window.

Whenever you run this test, the loop process will use the value of the loop iteration wherever you indicated using “TESTIM_ITERATOR” in a step. To learn how to view the results of the run, see VIEWING LOOP RUN RESULTS.

Example 2

You can use TESTIM_ITERATOR to define the conditions of a loop step, which will determine the number of times to repeat the loop.
The following procedure explains how to run a test that uses TESTIM_ITERATOR and the length of an array to set the loop to run once for each array element.

To create a loop condition using an array and TESTIM_ITERATOR:

  1. Choose a group step which contains the steps you want to include in the loop.

📘

Group steps can be identified by the Group icon (a picture of a folder).

  1. Hover over the arrow to the left of the group, and click on the + (plus sign) that appears. The Actions tab opens.
  1. Click on Add custom action.
    For more information about adding custom actions, see Creating a Custom Action. The Add Step window opens.
  1. In the Enter a name for the new step field, enter a (meaningful) name for this step.
  2. If this is a shared step (to be made available to reuse in this and other tests), keep the box next to Shared step selected. This is the default. Otherwise, deselect it.
    For more information about shared steps, see Reuse.
  3. Click Create Step.
    The condition editor opens, and the Custom Action Properties panel opens on the right-hand side.
  1. Enter the appropriate code to create your array. (For example: exportsTest.destinations = ["Madan", "Shenji", "Tongli", "Flagstaff", "Sant Cugat Del Valles", "Shaheying"];) For more information about exporting parameters, see Exports Parameters.
  2. Optionally edit the properties in the Custom Action Properties panel.
    • Description - Change the description of the step.
    • +PARAMS - Add JavaScript or HTML parameters. For more information, see Parameters in custom JavaScript steps
    • When this step fails - Specify what should happen if the step has failed.
    • When to run step - Specify when this step should be included in the test. Conditions may include the existence of an element/element text, or a custom JS function.
    • Override timeout - Keep waiting until the refresh occurs even after timeout.
  3. Click the back arrow to return to the main Editor window.
  1. Hover over the group step and then click on the Show Properties () icon. The Group Properties panel opens on the right-hand side.
  1. In the Group Properties panel, click on Repeat group.
  1. Select the Custom radio button. The Set condition window opens.
  1. In the function text box, type in the desired JavaScript condition using TESTIM_ITERATOR based on the array you just created, for example “return TESTIM_ITERATOR < destinations.length;”.
    If you have defined parameters, you can refer to those parameters in your JavaScript condition.

📘

If you are using DOM selectors other than HTML parameters (e.g. jQuery), then empty arrays are truthy, so you need to use $().length instead of $().

  1. If you would like to override the default timeout setting (30000 ms), click on the Override timeout button in the Custom Step Properties pane, and enter the desired timeout limit.
  1. Click the back arrow to return to the main Editor window.
  1. The loop is added to the step as indicated by the loop icon shown on the group step tile. Whenever you run this test, the loop process will loop over the contents in the array using the value of TESTIM_ITERATOR. To learn how to view the results of the run, see VIEWING LOOP RUN RESULTS.

Try it yourself

Click here to open a sample test in which the “Loop iterator” is used. Try running the test, and practice adjusting the configuration.

Viewing Loop Run Results

After running your test, the number of iterations the loop step was run is shown within the loop icon in the loop step.

You can go through each iteration and look at each of the results separately.
There are two methods for viewing loop results:

  • In the properties pane for the group step, or
  • By opening up the group step and viewing the iterations within the group. If one of the iterations failed, then when you open the group, you will be taken directly to the failed iteration.

To view Run Results from the group’s properties:

  1. Hover over the group step and then click on the Show Properties () icon. The Group Properties panel opens on the right-hand side.
  1. In the Group Properties panel, click on the iteration you would like to view. The group steps for the specified iteration are shown in the editor.
  1. Hover over the step you would like to view, and click on the Show Screenshot icon. The details for the specified step are shown.
  1. Click the right arrow to view the results of the next step in that group.
  1. Click the X to return to the previous screen.

To view Run Results from inside the group:

  1. Double-click on the group tile to open the group.
  2. Click on the Iteration dropdown list, and choose the iteration you would like to view.
  1. Hover over the step you would like to view, and click on the Show Screenshot icon. The details for the specified step are shown.
  1. Click the right arrow to view the results of the next step in that group.
  1. Click the X to return to the previous screen.

Updated about 17 hours ago

Repeat Group Loops


Repeat a group of steps using: while... do... loops & for loops

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.