Documentation: Retrieving OTP Sent by Email with Testim and getMailComponents Function

This document provides guidance on retrieving OTP codes sent via email in an end-to-end test using the getMailComponents function with Testim.

Purpose

The getMailComponents function automates OTP retrieval by fetching email OTPs for a specified user and service. This function can be integrated into Testim tests to handle email-based two-factor authentication (2FA) workflows without manual intervention.

Function Overview

The getMailComponents function retrieves the OTP by calling a backend service via an API request. It returns the OTP code along with the email's text and HTML content, allowing flexibility in verification steps.

getMailComponents Function Definition

const getMailComponents = async (
  user: string,             // Email address of the test user
  service: string,          // Identifier for the service sending the OTP
  options: { 
    verbose?: boolean,      // Optional flag to enable logging
    timeout?: number,       // Optional custom timeout in milliseconds
    registeredKey: string   // Required key for authorization
  }
): Promise<MailComponents> => { /* Implementation here */ }

Parameters

• user: string - The email address of the test user who is receiving the OTP.
• service: string - The identifier for the service sending the OTP (e.g., the service’s email address or name).
• options: object - Additional settings for OTP retrieval.
  • verbose: boolean (optional) - Enables detailed logging if set to true, useful for debugging.
  • timeout: number (optional) - Maximum time in milliseconds to wait for a response, defaulting to 5 minutes.
  • registeredKey: string - A required key to authenticate the API request.

Return Value

The function returns a Promise that resolves to an object containing the OTP code, the plain text content, and the HTML content of the email:

{ 
  code: string,    // The OTP code
  text: string,    // Plain text content of the email
  html: string     // HTML content of the email
}

Using getMailComponents in Testim

1. Install the Function: Import getMailComponents into your Testim project, using it within custom JavaScript code blocks to manage OTP retrieval.
2. Define Environment Variables: Set API_BASE_URL in Testim to point to the backend endpoint for OTP retrieval. This ensures Testim can access the required API.
3. Invoke getMailComponents in a Test Step: Use getMailComponents in a Testim test step, passing the required parameters (user, service, and options). Example:

   const emailOTP = async () => {
     try {
       const emailData = await getMailComponents("user@example.com", "ServiceName", {
         verbose: true,
         timeout: 300000,
         registeredKey: "YOUR_REGISTERED_KEY"
       });
       
       console.log(`Retrieved OTP: ${emailData.code}`);
       return emailData.code; // Use this OTP code for email-based 2FA verification
     } catch (error) {
       console.error(`Failed to retrieve OTP: ${error.message}`);
       throw error;
     }
   };
   

4. Validate OTP in Testim: Use the retrieved OTP code in a subsequent Testim step, where you enter it in the OTP input field to complete the 2FA process.

Example

Below is an example of using the OTP code within a Testim test step:

await emailOTP().then(code => {
  // Enter the OTP code in the OTP input field within Testim
  await testim.setValue({ selector: '#otp-input-field' }, code);
});

Error Handling

The function raises errors if:

• The request times out or encounters an issue.
• An invalid registeredKey is used.
• The API responds with an error.

Use verbose: true to print detailed error messages to the console.

Important Notes

• Environment Configuration: Ensure that API_BASE_URL and registeredKey are configured securely in Testim’s environment settings.
• Timeout Adjustments: Customize the timeout value to accommodate potential delays in email delivery.
• API Rate Limits: Verify that your usage complies with any API rate limits or quotas.

Conclusion

Integrating getMailComponents with Testim enables reliable, automated OTP handling for email-based 2FA flows, improving test efficiency and reducing manual steps in authentication tests.