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

Validate email

Validate sign-up and login flows

Testim offers a built-in email service which provides permanent and temporary email addresses. The Validate email step can be used with these email addresses to test your app sign-up or login flows.

📘

This is a pro feature only open to projects on our professional plan. To learn more about our professional plan, click here.

Generating a permanent email address

You can use a Testim-generated permanent email address for many purposes, including testing login flows and password reset flows.

To generate a permanent email address:

  1. In the left menu, click on the Settings icon.

The Project Settings page opens.

  1. Click the Email Service link.

The Email Service tab opens.

  1. Click the Generate Email Address button.

A random email address is generated and shown on the page. You can view the emails in your Inbox by clicking on Inbox.

📘

Emails sent to this email address are deleted after two hours.

Generating a temporary email address

There are times you may need to generate a new random email address every time you run a test, for example to test a sign-up flow multiple times with a new user each time. You can accomplish this using the Generate email address step.

📘

A temporary email address is NOT shown in the list of email addresses in the Email Service tab of the Settings page, and you cannot access your emails sent to this address through the Email Service tab.

This temporary email address (along with all of its associated emails) is deleted after two hours of when it was generated.

To generate a temporary email address:

  1. Hover over the (arrow symbol) where you want to add the step.

The action options are displayed.

  1. Click on the “M” (Testim predefined steps).
    The Predefined steps menu opens.
  1. Click on Actions.
    The Actions menu expands.
  1. Scroll down through the menu and select Generate email address.

📘

Alternatively, you can use the search box at the top of the menu to search for Generate email address.

A “Generate email address” step is added in the Editor.

  1. Hover over the newly created step, and click on the Show Properties () icon.

The Properties panel opens on the right-hand side.

  1. Fill in the properties as described below.
  • Description – The description of the step. (Default = Generate email address)
  • Variable name – The name of the JavaScript variable in which the temporary randomly generated email address will be stored. (Default = emailAddress)
  • Variable scope – The scope in which the variable can be passed:
    i. Local: Allows you to pass the emailAddress parameter between steps in the same scope. This is the default.
    ii. Test: Allows you to pass the emailAddress parameter between steps and groups in the same test.
    iii. Suite: Allows you to pass the emailAddress parameter between tests in the same test suite.
  • When this step fails – Specify what to do if the step fails.
  • When to run step – Specify conditions for when to run the step. For more info, see Conditions.
  • Override timeout – Allows you to override the default time lapse setting which causes Testim to register a fail for a test step, and specify a different time lapse value (in milliseconds).

When the test is run, the generated email address is stored in the designated variable, and can be used in future steps of the test.

Validating emails

There might be times when you want to verify various attributes of emails (e.g. subject, address, receiver, etc.) generated by your app. Using the Validate email step you can check the attributes of emails that have been sent to either permanent or temporary Testim-generated email addresses. The Validate email step is a predefined validation step that receives your Testim inbox content of a specified Testim email address as an array of all of the messages within that mailbox, contained in a parameter named messages with the following fields:

Field nameReturn type
attachmentsAttachmentCollection
fromEmailAddress
toEmailAddressCollection
subjectstring
date (time sent)Date
received_dateDate
message_idstring
headersInternetMessageHeaderCollection
html
textstring
mail_fromEmailAddress
rcpt_toEmailAddressCollection
sizenumber
projectIdstring
emailstring
expire_atstring
created_atstring
updated_atstring

📘

Even though emails sent to your Testim temporary email address are NOT shown in your Testim Email Service Inbox, they still exist (as long as the temporary email address exists), and you can use the Validate email step to validate their contents.

To validate an email:

  1. Hover over the (arrow symbol) where you want to add the step.

The action options are displayed.

  1. Click on the “M” (Testim predefined steps).
    The Predefined steps menu opens.
  1. Click on Validations.
    The Validations menu expands.
  1. Scroll down through the menu and select Validate email.

📘

Alternatively, you can use the search box at the top of the menu to search for Validate email.

The Add Step window is shown.

  1. In the Name 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 or other tests, keep the box next to Shared step selected (default), and choose a folder from the Select shared step folder list where you want this step stored. Otherwise, deselect the checkbox.
    For more information about shared steps, see Groups.
  3. Click Create Step.
    The function editor opens, and the Properties panel opens on the right-hand side.
  1. In the Properties panel, in the Description field, optionally edit the description of this step. The default description is “Run email validation”.
  2. Define the parameters you will need for your step as follows:
    a. In the Properties panel, click the + PARAMS button.
    b. JS parameter: If you would like to add a JavaScript parameter, select JS from the dropdown list and type in the JavaScript parameter.
    c. 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:
    • 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 pane. If you would like to view, replace or adjust the settings for the selected element, use the procedures described in Editing Target Element Properties.

d. The selected element is automatically named “param” or “element” (depending on whether you chose a JS parameter or HTML element). To assign a relevant name to the parameter/element, click on the edit icon and enter the desired name.

  1. In the Email address field, enter the email address from which messages will be fetched and validated.
    Actual email addresses should be surrounded by single or double quotes. A parameter (containing the value of an email address) from a previous step should not be surrounded by quotes.
  2. Optionally fill in the following Properties:
  • When this step fails – Specify what to do if this step fails.
  • When to run step – Specify conditions for when to run the step. For more information, see Conditions.
  • Override timeout – Allows you to override the default time lapse setting which causes Testim to register a fail for a test step, and specify a different time lapse value (in milliseconds).
  1. In the function text box, type in the desired JavaScript code. If you have defined parameters, you can refer to those parameters in your JavaScript code.

📘

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

  1. Click the back arrow to return to the main Editor window.

📘

If you opened your AUT to define an HTML element as a parameter, click on the Toggle Breakpoint button to remove the breakpoint.

The step is created.

Email validation examples

Validate sign-up subject line

You can use the Validate email step to validate the contents of the subject line of an email generated by your app that was sent to a Testim-generated email address.

Example Code:

if (messages && messages[0] ){
  return messages[0].subject === "Thank you for signing up";
}
return false;

Validate links in body

You can use the Validate email step to look for hyperlinks in the body of an email, and return the text component and link component of each link found.

Example Code:

if(messages.length !== 1) {
  throw new Error("Failed to find message in inbox " + emailAddress);
}

function getLinks(html) {
   var parser = new DOMParser();
   var doc = parser.parseFromString(html, "text/html");
   var linksElements =  Array.from(doc.querySelectorAll("a"));
  return linksElements.map(linkElement => ({text:linkElement.innerText,link:linkElement.getAttribute("href")}));
}

var emailLinks = getLinks(messages[0].html);

Updated about a month ago

Validate email


Validate sign-up and login flows

Suggested Edits are limited on API Reference Pages

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