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 custom validations and actions

Create complex validations using custom scripts

Using JavaScript in Your Tests

Using code in your tests is the best way to make sure they are reusable and easy to maintain.

Testim provides three categories of steps and you can add code to any of them using:

  1. Custom Validations.
  2. Custom Wait-For.
  3. Custom Actions.

Creating a Custom Validation

  • Go to http://www.google.com in the browser.
  • Start a new test, click on the ‘M’ on the right and choose Validations Tab ➔ Add Custom Validation:

Give a name to the new validation and click Confirm.

The editor will open:

This is a Custom (JS) Validation that expects you to return a boolean value. Returning true causes the validation to succeed, while returning false causes it to fail. Note that Custom Wait-For similarly creates a function that returns a boolean value, whereas Custom Action should have no return value.

Examples of passing and failing synchronous validations:

// This validation will always succeed.
return true;
// This validation will always succeed.
return 5 === 5;
// This validation will always fail after it times out.
return 5 === 6;
// This validation will always fail after it times out.
throw new Error('Validation failed!!!');

Go back to the test and run it. We run the following:
throw new Error('Validation failed!!!');

Note that the error message is displayed in the step's result panel at the step's properties panel in case the validation fails:

Creating an Asynchronous Validation via Promise

Have you ever asked out someone on a date?

Sometimes the answer is instantaneous, but on many occasions, that person needs some time to think about it (or at least give the impression of doing so before the inevitable rejection). So you ask: “When will you let me know?” and s/he says “I promise to let you know by 20:00 this evening.” So you go home with that promise in your pocket and this promise seems to you more like a time bomb than anything else.

Let’s take a closer look at what just happened. You made a query and was expecting a boolean return statement (‘return true;’ or ‘return false;’) and instead, you got something like this:

return new Promise(function(resolve, reject) {
  setTimeout(function() {
    if(sheLikesYou) {
    } else {
      reject("You're really a nice person but I’m not ready yet.");
  }, 10000);

The promise is given a function that can either resolve or reject.

We waited for some time using the setTimeout function.
The Javascript function setTimeOut receives two parameters:

  • Code to run
  • The wait time (in milliseconds).

Let’s use a promise to test a validation:
Go back into the editor, clear the previous code and type the following:

return new Promise(function(resolve, reject) {
  setTimeout(function() {
    if(7 === 7) {
    } else {
  }, 10000);

Run the test - at the end of the timeout the test should succeed.

Note that any text you type into the reject() function invocation will be displayed in the step's property panel in case the validation fails.

Creating a Custom Action

  • Delete the Custom Validation we just made.
  • Click on the ‘M’ on the right and choose Actions tab ➔ Add Custom Action:

In the editor type:

window.location.href = 'https://testim.io/';

Run the test - it should now begin by navigating to the base URL in the Setup (which in our case is http://www.google.com) and then immediately navigate to the Testim homepage.

Chrome Dev Tools Debugger

If you add the line:

//Your code

to you JavaScript code, whenever you test is running locally, if your Chrome Dev Tools is opened (Press F-12 (⌥⌘I on Mac) to open it), the Custom step code will stop, and you'll be able to see it in Chrome Dev Tools debugger with all its features like watching variables, step into, step over, etc.

Custom validation examples

The custom validation we'll demonstrate are:

  • How to validate the value of a number in the recorded app
  • How to validate that two elements have the same text

How to validate a numeric value in your app?

When you need to validate a numeric value of an HTML element, sometimes with extra characters - like prices in your page, presented with the currency: $1,000 - you need to convert this string to a number, and then validate it.
In this example we will:

  • Create a new custom validation step.
  • Capture a label that contains the number in our recorded app, and turn in into a parameter (here's a reminder).
  • Name the HTML "amountLabel".
  • Write the following JS to validate that it's not over the value of 1000.


// Remove string chars (e.g "$") and turn the price label to a number:
var amount = Number(amountLabel.innerText.replace(/[^\-0-9\.]+/g,""));

// Validate if the number is bigger than 1000:
if(amount > 1000) {
  throw new Error('Amount should not be over 1000! Actual value:' + amount);
} else {
  return true;

Compare two text elements on screen

When you need to compare two elements on the screen, and want to make sure they have the same text - here is how to do it:We will add a first HTML parameter named "first_label", and a second HTML parameter named "second_label" (see how to add parameters), and validate that the text in first_label equals to the text in second_label:

var equal = firstLabel.innerText === secondLabel.innerText;

if(!equal) {
  throw new Error('Labels are not equal. First label: ' + firstLabel.innerText + 
                  'Second label: ' + secondLabel.innerText);

return equal;

If you'll add another item to the cart you'll see that the two texts are different and the step will fail:

Notice the informative error message we return when the labels are not equal.

For more JS actions, see here.

Want more guides? Tell us about it!

Updated 3 months ago

Add custom validations and actions

Create complex validations using custom scripts

Suggested Edits are limited on API Reference Pages

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