cypress-get-otp

A Cypress custom command for generating OTP (One-Time Password) codes in your tests. This package provides a simple and reliable way to generate TOTP (Time-based One-Time Password) codes during automated testing.

Features

• 🔐 Generate TOTP codes using secret keys
• ⚙️ Customizable options (digits, period, algorithm, etc.)
• 🧪 TypeScript support with full type definitions
• 📦 Lightweight with minimal dependencies. Based on https://github.com/hectorm/otpauth, which looks well maintained - kudos to the author and contributors.
• 🚀 Easy integration with existing Cypress tests

Installation

npm install cypress-get-otp

Setup

1. Import the command

Add the following import to your Cypress support file (usually cypress/support/e2e.js):

import "cypress-get-otp";

2. TypeScript support (optional)

If you're using TypeScript, the package includes type definitions that will be automatically picked up by your IDE.

Usage

Basic Usage

describe("Login with OTP", () => {
  it("should login with a valid OTP code", () => {
    const secret = "G5HJRA652X3NOFSE"; // Your OTP secret

    cy.getOTP(secret).then((otp) => {
      cy.visit("/login");
      cy.get('[data-cy="otp-input"]').type(otp);
      cy.get('[data-cy="login-button"]').click();
    });
  });
});

Advanced Usage with Custom Options

describe("OTP with custom settings", () => {
  it("should generate 8-digit OTP with custom period", () => {
    const secret = "G5HJRA652X3NOFSE";

    cy.getOTP(secret, {
      digits: 8, // 8-digit code instead of default 6
      period: 30, // 30-second period instead of default 30
      algorithm: "sha1", // Use SHA-1 algorithm
    }).then((otp) => {
      expect(otp).to.have.length(8);
      // Use the OTP in your test...
    });
  });
});

API Reference

cy.getOTP(secret, options?)

Generates a TOTP code using the provided secret and options.

Parameters:

• secret (string): The secret key for generating the OTP
• options (object, optional): Configuration options for the OTP generation

Returns:

A Cypress chainable that resolves to the generated OTP string.

Examples

Testing 2FA Login Flow

describe("Two-Factor Authentication", () => {
  it("should complete 2FA login process", () => {
    const userSecret = "G5HJRA652X3NOFSE";

    // Step 1: Login with username/password
    cy.visit("/login");
    cy.get('[data-cy="username"]').type("testuser");
    cy.get('[data-cy="password"]').type("password123");
    cy.get('[data-cy="login-button"]').click();

    // Step 2: Generate and enter OTP
    cy.getOTP(userSecret).then((otp) => {
      cy.get('[data-cy="otp-input"]').type(otp);
      cy.get('[data-cy="verify-otp"]').click();
    });

    // Step 3: Verify successful login
    cy.url().should("include", "/dashboard");
    cy.get('[data-cy="welcome-message"]').should("be.visible");
  });
});

Testing OTP Expiration

describe("OTP Expiration", () => {
  it("should handle OTP expiration correctly", () => {
    const secret = "G5HJRA652X3NOFSE";

    // Generate first OTP
    cy.getOTP(secret, { period: 3 }).then((otp1) => {
      cy.get('[data-cy="otp-input"]').type(otp1);
    });

    // Wait for OTP to expire
    cy.wait(4000);

    // Generate new OTP (should be different)
    cy.getOTP(secret, { period: 3 }).then((otp2) => {
      expect(otp2).to.not.equal(otp1);
    });
  });
});

Development

Running Tests

# Open Cypress Test Runner
npm run cy:open

# Run tests headlessly
npm run cy:run

Code Formatting

npm run style

Dependencies

• cypress - End-to-end testing framework
• otpauth - OTP generation library.

License

MIT

Author

Sergiu Bacanu

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.