Documentation: Generating Time-Based OTP with Cypress

This guide explains how to generate a Time-Based One-Time Password (TOTP) within a Cypress test environment using the otp-device-sync service. The service allows you to generate TOTPs either through an HTTP API or via the otp-device-sync JavaScript library. Each method has its advantages depending on your testing requirements and setup.

Choosing Between HTTP API and JavaScript Library

1. HTTP API
   • Best For: Simple setups with fewer dependencies or cases where Cypress is primarily used for making HTTP requests.
   • Advantages:
     • Direct integration with cy.request, leveraging Cypress’ built-in HTTP capabilities.
     • Easy to configure, with straightforward response handling and timeout control.
   • Usage: Sends an HTTP request to generate a time-based OTP.
2. JavaScript Library
   • Best For: Situations where a programmatic approach is preferred, especially when using other features of otp-device-sync.
   • Advantages:
     • Provides a ready-to-use function with built-in error handling.
     • Verbose logging option for detailed debugging.
     • Reduces redundancy by encapsulating the API call in a reusable function.
   • Usage: Import and use getTimeBasedCode to generate the OTP.

Option 1: Using the HTTP API in Cypress

Example Code

Cypress.Commands.add('generateTimeBasedOTP', (userLabel, issuerService, registeredKey) => {
  const API_BASE_URL = Cypress.env('API_BASE_URL');

  return cy.request({
    method: 'GET',
    url: `${API_BASE_URL}/retrieve/totp`,
    qs: {
      label: userLabel,
      issuer: issuerService,
      registeredKey,
    },
    failOnStatusCode: false,
  }).then((response) => {
    if (response.status === 200) {
      const { code } = response.body;
      cy.log(`Generated TOTP: ${code}`);
      return code;
    } else {
      throw new Error(`Error generating TOTP: ${response.body}`);
    }
  });
});

// Usage in a Cypress test
cy.generateTimeBasedOTP("testUser", "testService", "YOUR_REGISTERED_KEY").then((otpCode) => {
  cy.log(`TOTP Code: ${otpCode}`);
});

Option 2: Using the JavaScript Library in Cypress

Setup

1. Install the Library:
   • Run npm install otp-device-sync to add the library to your Cypress project.
2. Import and Use the Function:
   • Use getTimeBasedCode to generate the TOTP directly in your Cypress test.

Example Code

import { getTimeBasedCode } from 'otp-device-sync';

Cypress.Commands.add('generateTimeBasedOTP', (userLabel, issuerService, registeredKey) => {
  return getTimeBasedCode(userLabel, issuerService, { registeredKey, verbose: true })
    .then((otpCode) => {
      cy.log(`Generated TOTP: ${otpCode}`);
      return otpCode;
    })
    .catch((error) => {
      throw new Error(`Error generating TOTP: ${error.message}`);
    });
});

// Usage in a Cypress test
cy.generateTimeBasedOTP("testUser", "testService", "YOUR_REGISTERED_KEY").then((otpCode) => {
  cy.log(`TOTP Code: ${otpCode}`);
});

Key Points

• HTTP API:
  • Ideal for lightweight, dependency-free setups within Cypress.
  • Utilizes native cy.request features, providing control over request options and error handling.
• JavaScript Library:
  • Encapsulates the request and handles common cases, which simplifies the Cypress code.
  • Built-in options for verbosity and error logging aid in debugging.

Conclusion

Choose the HTTP API if you want a direct integration that leverages Cypress's native request-handling capabilities. Opt for the JavaScript library if you prefer an encapsulated, simplified approach with detailed error handling and logging options. Both methods enable seamless TOTP generation, supporting 2FA flows within your Cypress test suite.