Documentation: Retrieving OTP Sent by SMS with Testim and getSMSCode Function

This document provides step-by-step instructions on how to retrieve SMS-based OTP (One-Time Password) codes in an end-to-end test using the getSMSCode function with Testim.

Purpose

The getSMSCode function enables automated tests to retrieve OTP codes sent via SMS to a specified user and service. It is particularly useful for automated workflows, like those built in Testim, to validate 2FA (two-factor authentication) flows without manual intervention.

Function Overview

The getSMSCode function retrieves the OTP by making an API request to a pre-configured endpoint. It accepts parameters for the user’s phone number, the service sending the OTP, and several optional parameters for enhanced flexibility and error handling.

getSMSCode Function Definition

const getSMSCode = async (
  user: string,             // Phone number 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<{ code: string }> => { /* Implementation here */ }

Parameters

• user: string - The phone number of the test user receiving the OTP.
• service: string - The identifier for the service from which the OTP is sent (e.g., the service’s phone number or name).
• options: object - Additional options for retrieving the OTP.
  • verbose: boolean (optional) - Enables detailed logging if set to true. Useful for debugging.
  • timeout: number (optional) - Specifies the maximum time to wait for a response, in milliseconds. Defaults 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:

{ 
  code: string // The OTP code retrieved from the SMS
}

Using getSMSCode in Testim

1. Install the Function: Import getSMSCode into your Testim project’s custom JavaScript code block where you handle OTP retrieval.
2. Define Environment Variables: Set the API_BASE_URL environment variable in Testim. This variable points to the backend service responsible for OTP retrieval.
3. Invoke getSMSCode in a Test Step: Use the function in a Testim step, passing the required parameters (user, service, and options). Here’s an example:

   const otpRetrieval = async () => {
     try {
       const otpResponse = await getSMSCode("1234567890", "ServiceName", {
         verbose: true,
         timeout: 300000,
         registeredKey: "YOUR_REGISTERED_KEY"
       });
       
       console.log(`Retrieved OTP: ${otpResponse.code}`);
       return otpResponse.code; // Use this code for 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 subsequent steps for validation, such as entering it in the OTP field and completing the 2FA step.

Example

Here’s a complete example in a Testim test step:

await otpRetrieval().then(code => {
  // Use the retrieved OTP code in your Testim step, e.g., to input it in a field
  await testim.setValue({ selector: '#otp-input-field' }, code);
});

Error Handling

The function throws errors if:

• The request times out or fails.
• An invalid registeredKey is provided.
• The API responds with an error message.

Use the verbose option to output additional error details to the console.

Important Notes

• Environment Configuration: Make sure API_BASE_URL and registeredKey are set securely in Testim.
• API Limitations: Ensure your usage aligns with any rate limits or quotas in place on the OTP retrieval API.
• Timeout Handling: Adjust the timeout parameter based on expected delays in SMS delivery.

Conclusion

Integrating getSMSCode with Testim allows efficient and automated handling of SMS OTPs, streamlining tests for 2FA flows. This approach provides robust OTP management, aiding in faster test execution and improved automation reliability.