Disclosure: I work with HeroSMS, the virtual number provider used in the examples.

Your Cypress SMS OTP test hits a wall as soon as your sign-up, login or SMS 2FA form sends a real code: the browser under test has no phone, and cy.intercept can only pretend the SMS went out. That's fine for most runs, but it never proves that a real SMS reaches a real number in your launch country, or that your app accepts the code.

This tutorial builds that check for your own app: rent a number from an API, read the code on the Node side with cy.task, type it, release the number whether the test passes or fails, and run it nightly in GitHub Actions.

Can Cypress read SMS?

No. Cypress drives a browser and can't reach a phone or SIM. To receive SMS in Cypress, call an SMS API from Node with cy.task(): the task polls until the message arrives, extracts the code and returns it to the test, which types it into your form.

Cypress SMS OTP: mock, test credentials or a real number

Twilio's test credentials don't connect to real phone numbers, and Firebase's fictional test numbers (up to 10, each with a fixed code) send no SMS. Hosted services such as Mailosaur and MailSlurp give you real numbers with their own Cypress integrations (Mailosaur ships cy.mailosaurGetMessage, and its guide requires an account with SMS enabled). If your second factor is an authenticator app (TOTP), skip the phone and generate codes from the shared secret, for example with otplib inside a cy.task.

I covered the same mocks-on-PR, real-SMS-on-schedule split in Python and for Playwright with a webhook; this Cypress version polls from the config process, which already runs in Node, so you don't need a public webhook URL.

What you need

• Cypress 16.2 or later on Node 22, 24 or 26.
• A HeroSMS API key and some balance. You buy an activation: one number reserved for one service in one country for about 20 minutes (the exact end is in expiredAt). Numbers cover 180+ countries, so you can usually test in the country you launch in.
• These environment variables, read only by Node:

export HEROSMS_API_KEY="<your API key>"
export OTP_SERVICE="<service code>"   # 2-4 letters
export OTP_COUNTRY="<country ID>"     # an integer
export APP_URL="https://staging.example.com"
# optional: export HEROSMS_MAX_PRICE="<price cap per number>"

Service codes and country IDs come from the getServicesList and getCountries endpoints in the HeroSMS API reference (key required); GET /activations/offers/sms without filters also returns them: service codes are the keys of data, country IDs the keys inside each service.

Keeping the API key out of the browser

The variables above deliberately have no CYPRESS_ prefix. Cypress copies CYPRESS_* variables into its env config, which a spec can read with cy.env() (environment variables guide), and spec and support files run in the browser. Unprefixed variables stay in the Node process that runs cypress.config.js. Never pass the key as a cy.task argument either: the Command Log prints arguments.

Step 1: a small SMS API client in Node

// cypress/tasks/herosms.js - runs in Node only, never in the browser
const API = 'https://hero-sms.com/api/v1';

class HeroSmsError extends Error {
  constructor(status, body, retryAfter) {
    super(`HTTP ${status} ${body.title ?? ''}: ${body.details ?? ''}`);
    this.name = 'HeroSmsError';
    this.status = status;
    this.title = body.title ?? '';
    this.info = body.info;
    this.retryAfter = retryAfter;
  }
}

async function call(method, path, body) {
  const key = process.env.HEROSMS_API_KEY;
  if (!key) throw new Error('HEROSMS_API_KEY is not set');
  const res = await fetch(API + path, {
    method,
    headers: {
      Authorization: `ApiKey ${key}`,
      Accept: 'application/json',
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(15_000), // a stuck request can't hang the task
  });
  const text = await res.text();
  if (res.status >= 400) {
    let err = {};
    try { err = JSON.parse(text) ?? {}; } catch { /* not JSON */ }
    const retryAfter = Number.parseInt(res.headers.get('retry-after') ?? '', 10) || 0;
    throw new HeroSmsError(res.status, err, retryAfter);
  }
  return text ? JSON.parse(text) : null; // 204 No Content -> null
}

async function buyNumber(service, country, maxPrice) {
  const res = await call('POST', '/activations', {
    service, country, amount: 1, verificationType: 'sms',
    ...(maxPrice ? { maxPrice } : {}),
  });
  if (!res?.data?.[0]) throw new Error('POST /activations returned no activation');
  return res.data[0];
}

module.exports = {
  HeroSmsError,
  buyNumber,
  lastOtp: (id) => call('GET', `/activations/${id}/otp/last`),
  finish: (id) => call('POST', `/activations/${id}/finish`), // closes it, no refund
  cancel: (id) => call('DELETE', `/activations/${id}`), // cancels and refunds
};

Errors come back as JSON with title and details. Each request aborts after 15 seconds, since the Cypress docs don't say whether a timed-out task's handler is stopped. phone comes back as an integer without the +.

Step 2: receive the SMS in Cypress with cy.task

// cypress.config.js
const { defineConfig } = require('cypress');
const sms = require('./cypress/tasks/herosms');

const open = new Map(); // activationId -> { boughtAt, gotOtp }, lives for the whole run
const CLOSED = new Set(['ACTIVATION_NOT_ACTIVE', 'CANCELED', 'FINISHED', 'REFUNDED']);
const sleep = (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms)));
const dropped = (e) => e.name === 'TimeoutError'
  || (e instanceof TypeError && e.message === 'fetch failed');

async function buy() {
  const service = process.env.OTP_SERVICE;
  const country = Number.parseInt(process.env.OTP_COUNTRY ?? '', 10);
  const cap = process.env.HEROSMS_MAX_PRICE;
  const maxPrice = cap ? Number(cap) : undefined;
  if (!service || !Number.isInteger(country) || Number.isNaN(maxPrice)) {
    throw new Error('Set OTP_SERVICE and OTP_COUNTRY; HEROSMS_MAX_PRICE must be a number');
  }
  const a = await sms.buyNumber(service, country, maxPrice);
  open.set(a.id, { boughtAt: Date.now(), gotOtp: false });
  return { id: a.id, phone: `+${a.phone}` };
}

async function waitForCode({ id, timeoutMs = 90_000 }) {
  const deadline = Date.now() + timeoutMs;
  let delay = 2_000;
  while (Date.now() < deadline) {
    try {
      const otp = (await sms.lastOtp(id))?.data ?? {};
      const code = otp.smsCode || otp.smsText?.match(/\b\d{4,8}\b/)?.[0];
      if (code) {
        const entry = open.get(id);
        if (entry) entry.gotOtp = true;
        return code; // the only value that crosses into the browser
      }
      if (otp.smsText) throw new Error('SMS has no 4-8 digit code; check your template');
    } catch (e) {
      if (e.status === 429) {
        await sleep(Math.min((e.retryAfter || 5) * 1000, deadline - Date.now()));
        continue;
      }
      // 400/404 on an open activation = no SMS yet; a slow or dropped request is retried
      const notYet = e instanceof sms.HeroSmsError
        && [400, 404].includes(e.status) && !CLOSED.has(e.title);
      if (!notYet && !dropped(e)) throw e;
    }
    await sleep(Math.min(delay, deadline - Date.now()));
    delay = Math.min(delay * 1.5, 10_000);
  }
  throw new Error(`No SMS for activation ${id} within ${timeoutMs / 1000}s`);
}

// Never throws: a cleanup error must not hide the real test failure
async function release(id, wait = false) {
  const entry = open.get(id);
  if (!entry) return null;
  try {
    if (entry.gotOtp) {
      await sms.finish(id); // the code was used: close it, no refund
    } else {
      try {
        await sms.cancel(id); // no SMS: cancel, money back to balance
      } catch (e) {
        if (e.title === 'OTP_RECEIVED') {
          await sms.finish(id); // the SMS came late
        } else if (e.title === 'EARLY_CANCEL_DENIED' && wait) {
          const minSec = Number(e.info?.minActivationTime) || 120;
          await sleep(entry.boughtAt + minSec * 1000 + 5_000 - Date.now());
          return release(id); // one more try, no more waiting
        } else {
          throw e;
        }
      }
    }
    open.delete(id);
  } catch (e) {
    // Too early, rate-limited, server or network error: keep it for the next sweep
    const later = !(e instanceof sms.HeroSmsError) || e.status >= 500
      || e.status === 429 || e.title === 'EARLY_CANCEL_DENIED';
    if (!later) open.delete(id);
    console.error(`[otp] release ${id}: ${e.message}`);
  }
  return null;
}

async function releaseAll(wait = false) {
  for (const id of [...open.keys()]) await release(id, wait);
  return null;
}

module.exports = defineConfig({
  retries: { runMode: 1, openMode: 0 }, // every attempt buys a new number
  e2e: {
    baseUrl: process.env.APP_URL || 'http://localhost:3000',
    // jobs without the key (PR runs, forks) never pick up the paid spec
    excludeSpecPattern: process.env.HEROSMS_API_KEY ? [] : ['**/*.real-sms.cy.js'],
    setupNodeEvents(on, config) {
      on('task', {
        'otp:buy': buy,
        'otp:wait': waitForCode,
        'otp:release': (id) => release(id),
        'otp:releaseAll': () => releaseAll(),
      });
      on('after:run', () => releaseAll(true)); // last chance; may wait out the early-cancel window
      return config;
    },
  },
});

Every handler returns a value or null, since a task that resolves with undefined fails. The registry lives in the config process: it spans every spec in a run, and each parallel CI machine has its own. If your package.json has "type": "module", name both files .cjs and require ./cypress/tasks/herosms.cjs with the extension.

Waiting for the SMS without cy.wait()

A fixed cy.wait(10000) is too short for a slow carrier and wastes time on a fast one. cy.task runs its handler once and never retries it, so the polling lives in Node, backs off from 2 to 10 seconds and returns as soon as the code arrives.

GET /activations/{id}/otp/last returns smsCode (the code) and smsText (the full message), and either can be null. If smsCode is empty, the regex takes the first 4-8 digit number, so adjust it to your SMS template. The response before the first SMS isn't documented, so 400, 404 and an empty data count as "not yet" unless title says the activation is closed (a 404 from a wrong id will look like a timeout). The loop also honors Retry-After on 429, which only the offers endpoint documents.

Step 3: automate the OTP sign-up or login test in Cypress

cy.getSmsCode() and typing into six OTP boxes

// cypress/support/commands.js - bundled into the browser: no keys here
Cypress.Commands.add('getSmsCode', (id, timeoutMs = 90_000) =>
  // Node gives up at timeoutMs; +20 s covers its last request
  cy.task('otp:wait', { id, timeoutMs }, { timeout: timeoutMs + 20_000, log: false }));

// [data-cy=otp] is either the input itself or a wrapper around one box per digit
Cypress.Commands.add('typeOtp', (code) => {
  cy.get('[data-cy=otp]').then(($otp) => {
    if ($otp.is('input')) {
      cy.wrap($otp).clear().type(code, { log: false });
      return;
    }
    cy.get('[data-cy=otp] input').should('have.length', code.length);
    [...code].forEach((digit, i) => {
      cy.get('[data-cy=otp] input').eq(i).clear().type(digit, { log: false });
    });
  });
});

For split inputs, typeOtp types one digit per box by index, so it doesn't rely on the component moving focus, and re-querying each box survives re-renders.

The spec, with a wrong-code check

// cypress/e2e/otp-signup.real-sms.cy.js
describe('Cypress SMS OTP sign-up', () => {
  let activation;

  beforeEach(() => {
    activation = undefined;
    cy.task('otp:releaseAll', null, { log: false, timeout: 120_000 }); // leftovers
    cy.task('otp:buy', null, { timeout: 30_000 }).then((a) => { activation = a; });
  });

  afterEach(() => {
    if (activation) cy.task('otp:release', activation.id, { log: false });
  });

  it('rejects a wrong code, then signs up with the real one', () => {
    cy.visit('/signup');
    cy.get('[data-cy=phone]').type(activation.phone);
    cy.get('[data-cy=send-code]').click();

    cy.getSmsCode(activation.id).then((code) => {
      const wrong = (code.startsWith('1') ? '2' : '1') + code.slice(1);
      cy.typeOtp(wrong);
      cy.get('[data-cy=verify]').click();
      cy.get('[data-cy=otp-error]').should('be.visible');

      cy.typeOtp(code);
      cy.get('[data-cy=verify]').click();
    });
    cy.location('pathname').should('eq', '/welcome');
  });
});

• If your component submits on the last digit, drop the verify clicks and assert the result directly.
• For a login or SMS 2FA test, visit your login page instead, type the code at the second-factor prompt and assert the session, for example cy.getCookie('session').should('exist'). Expired-code and rate-limit tests follow the same shape: wait out your app's code lifetime or hit its limit, then assert the error.
• If verification runs on another origin, wrap it in cy.origin() and pass the code via args.
• log: false hides commands, not the input: failure screenshots still show the digits, so treat CI artifacts as sensitive.
• If your app rejects the number, release it and buy another; phoneException in the purchase body excludes prefixes up front. The API also offers a free replacement via POST /activations/{id}/replace; if you use it, register the activation it returns in open the way buy() does, so cleanup still releases it.
• If your form splits the country picker from the number, strip the country calling code from activation.phone before typing (the purchase response has it as countryPhoneCode; return it from buy() too).

Step 4: cleanup that survives failed tests

The Cypress best practices warn that after hooks may not run if a run is interrupted, and recommend cleaning up before tests. So cleanup has four layers:

1. afterEach releases the current number: the normal path.
2. beforeEach sweeps leftovers before buying. With retries, every attempt re-runs it and buys a new number; the failed attempt's number is closed if its early-cancel window has passed, or stays in the registry.
3. after:run releases the rest and is the only layer that waits: the reference's error examples include an EARLY_CANCEL_DENIED refusal during a number's first 2 minutes, so a test that fails within seconds gets its refund here. In cypress open it fires only with experimentalInteractiveRunEvents: true.
4. If the runner itself dies, no Node code runs. Unused numbers are refunded to your balance, and GET /activations lists anything still open.

release() branches on the error title, not the HTTP status, because the reference doesn't document how the v1 endpoint reports these refusals. A late SMS (OTP_RECEIVED) gets finish; a 5xx, 429 or network error keeps the number for the next sweep. Other refusals are only logged; that number stays open until it expires.

Step 5: run it nightly in GitHub Actions

# .github/workflows/otp-nightly.yml
name: otp-nightly
on:
  schedule:
    - cron: '0 4 * * 1-5' # 04:00 UTC on weekdays; every run buys a number
  workflow_dispatch:

concurrency:
  group: otp-nightly
  cancel-in-progress: false # a canceled run never reaches after:run

jobs:
  real-sms:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - uses: cypress-io/github-action@v7
        with:
          spec: cypress/e2e/otp-signup.real-sms.cy.js
        env:
          HEROSMS_API_KEY: ${{ secrets.HEROSMS_API_KEY }}
          OTP_SERVICE: ${{ vars.OTP_SERVICE }}
          OTP_COUNTRY: ${{ vars.OTP_COUNTRY }}
          HEROSMS_MAX_PRICE: ${{ vars.HEROSMS_MAX_PRICE }}
          APP_URL: ${{ vars.APP_URL }}

With the Cypress GitHub Action, the step's env: reaches process.env in the config process, not the browser. Your PR workflow doesn't pass the key, so excludeSpecPattern keeps the paid spec out of PR runs. Scheduled workflows run on the default branch in UTC, can start late, and are disabled after 60 days without activity in a public repository.

Use it on your own app only

Test only apps you own or are authorized to test. A rented number is yours only for the activation window, so don't tie it to an account you'll need later.

Wrap-up

Keep mocks on every PR and add one scheduled run against a real number: it catches what mocks can't, such as delivery failures, broken SMS templates and country-specific quirks. If you'd rather have codes pushed than polled, the HeroSMS API reference documents an sms-incoming webhook; the Playwright post above shows that setup.

This post was drafted with AI assistance and checked against the HeroSMS API reference and the Cypress docs.