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


Add conditions to your tests

Adding conditions to your test

Adding conditions to your test lets you control if some step will run or not.
You can add conditions to any type of step, including a group step.
There are 3 types of conditions: Element, Custom, and Never (Skip).

Element Conditions
Element condition allows you to specify whether to run a step if the element you chose is visible or to run it is its not. The element can be any DOM object, such as property ID, text, or class.

  • Element visible condition: will pass if the element is visible in the application.
  • Element not visible condition: will pass if the element does not exist in the application.

Element Text Conditions
Element text condition will run the step if the specific text that you chose exists.

Custom Conditions

  • Custom conditions: defined by JavaScript as any JavaScript step.
  • A custom condition must return a Truthy value in order to run the step that contains the condition.
  • A custom condition, just like any other JavaScript step, can have HTML or JavaScript parameters.

Never Conditions

  • Never step: can be useful when you want to temporarily skip a step.

Popular use cases for conditions

  • Running a login step if the user is logged out - it's important to consider that testing locally is different than testing using a CI. When you test using CI, a fresh browser is opened and you'll probably want to login first, while locally you are probably already logged in. By using conditions you will be able to do it easily. Click here to run a demo test with this example. Look at the revisions history to see the different examples.
  • Populate table data only when it's empty - that's how you can be sure your tests are clean and start from the same initial state.

Element condition

In this tutorial, we will add a condition to a group ("login") to check if the user is logged in or not.
If the user is not logged in --> the login group will run.
If the user is already logged in --> the login group will be skipped.

1. Create a test

Our test is composed of:

  • Navigation to the "Testim Demo" page.
  • Login group - regular login group of the site.

2. Add a condition

  • Click the "Login" step.
  • Open property panel.
  • Choose "Element" in "when to run step".
  • Select in your application the element for the condition.

Note: If you get the message "No app to choose an element from" this means that you must first run the test so you can select a component from within your application.

3. Run
Run your test and see how the condition works. As you may notice, any conditional group or step are marked with a rhombus.

When you run your test, if the condition returns Truthy value, it means that the user is logged out and the login group should be played:

The rhombus will be green when the login group runs (despite whether the step was successful or not).

If the condition returns a Falsy value, it means the user is already logged in.
The login group will be skipped and the rhombus will be red.

If you want your condition to check that the element exists in the application, change the radio button from visible to not visible state. If the element exist in the DOM but it is just not visible, the condition will fail.

Element text

While element condition allows you to run the step if the element you chose is visible or not, element text condition will run the step if the text you chose exists.

Define the condition

  • Go back to the step that needs the condition.
  • This time choose "Element text" instead of "Element".
  • Select in your application the text for the condition.

You can also put a Regex expression, a short JS expression and even a parameter as "Expected value".

Custom condition

In some cases, you'll want to add a condition that will include more than just validating an element visible. You may want to check an element value or enable custom JavaScript code for the condition. This is done by a custom condition.

We see a lot of applications that login page can be identified according to the URL. Let's see how to check that.

Define the condition

  • Go back to the step that needs the condition.
  • This time choose "Custom" instead of "Element".
  • In the JavaScript editor that opens, type: return window.location.href===""

That's it!
You can add any custom condition you need...

Custom condition with parameters

In JavaScript custom steps we can use elements from our application in a very easy way.
In the example we presented earlier, the element condition element was not sufficient.
After login the element does not change, so we will also need to check the text on the login button.

  • Add custom condition.
  • Click "Params" and add HTML parameter.
  • Select the element you'd like to check. In our example, it's the login/sign-in button.
  • Once chosen, you should see a thumbnail of the selected element. We'll rename the new HTML parameter name to be "loginButton".
  • Now, you can add the condition by relating it to the HTML element you chose: The condition we added checks if the HTML element (loginButton) exists and if its text value is "Login/Sign up".
return loginButton.innerText === 'LOG IN';

Note: In this example, we used an HTML parameter as a dependency injection to check if the user is logged out or not. If you're using other types of DOM selector (e.g. jQuery), note that empty arrays are Truthy, so use $(<query>).length instead of $(<query>)


In some cases, you may want to retry again before declaring a true/false condition. e.g. long page loading time might require wait time before checking the condition.

Retry when condition fails:

Defines a time for retries when the condition is false before continue with the next steps.
By default, if the condition returns false on first try, the step is immediately skipped.
If you want the system to try again before moving on, use this option.

Minimum pass duration when condition pass:

As a default, if the condition is true the step will be executed. In some cases you might want to retry again before declaring a condition true and execute the step.
Note: If the condition returns false on the first attempt, it will not retry again even if this option was marked.

How to change those times:

Edit or delete a condition

You can easily edit or delete any condition by clicking the step or group that contains a condition, and choosing the relevant action from the properties panel:

Updated about a month ago


Add conditions to your tests

Suggested Edits are limited on API Reference Pages

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