How to test SMS OTP in React Native with Detox

Step 1: route the backend's SMS to the mock

The flow is: app calls POST /auth/send-code on your backend, the backend asks Twilio, Vonage or another provider to send the SMS. In the test or staging backend, point that provider's SDK at otpmock with one option; each provider's option is on its provider page. Make sure the Detox build of the app (for example a debug or e2e configuration) talks to that backend. Nothing in the app itself changes.

Step 2: add the helper to your e2e folder

Download the dependency-free helper otpmock.ts (or otpmock.mjs) into e2e/. It uses the global fetch available in Node 18+, which is where Jest runs your Detox tests. It calls:

GET https://api.otpmock.com/v1/inbox/{phone}/code?since={unix_ms}
Authorization: Bearer $OTPMOCK_API_KEY

200 {"code":"482913","messageSid":"SM…","body":"Your code is 482913","receivedAt":1791417652342}

It polls every 300 ms while the API answers 404 and throws after the timeout (15 s by default).

Step 3: the Detox test

import { by, device, element, expect } from "detox";
import { OtpMock } from "./otpmock";

const otp = new OtpMock({
  baseUrl: process.env.OTPMOCK_URL ?? "https://api.otpmock.com",
  apiKey: process.env.OTPMOCK_API_KEY!,
});

describe("phone verification", () => {
  beforeEach(async () => {
    await device.launchApp({ newInstance: true, delete: true });
  });

  it("verifies the phone number with an SMS code", async () => {
    const phone = otp.randomPhone(); // +1555XXXXXXX, unique per test

    await element(by.id("phone-input")).typeText(phone);
    const since = Date.now() - 5_000; // margin for clock skew
    await element(by.id("send-code-button")).tap();

    const { code } = await otp.waitForCode(phone, { since, timeout: 20_000 });

    await element(by.id("code-input")).typeText(code);
    await element(by.id("verify-button")).tap();
    await expect(element(by.id("welcome-screen"))).toBeVisible();
  });
});

by.id matches the component's testID prop. The waitForCode call runs in Node on the test runner, not inside the app, so the simulator or emulator never talks to otpmock.

Passing the API key

Jest inherits the environment of the detox test process, so export the key before running:

export OTPMOCK_API_KEY=...   # from your CI secret store
detox test --configuration ios.sim.debug

If your Jest config transforms TypeScript only through Babel, the helper works as is. If you use plain JavaScript tests, import otpmock.mjs or convert the helper to CommonJS to match your Jest setup.

SMS autofill and one-time-code fields

With textContentType="oneTimeCode" (iOS) or autoComplete="sms-otp" (Android), real devices offer the received code above the keyboard. With a mock inbox no SMS reaches the device, so that suggestion never appears and the test types the code. If your screen relies on a library that auto-reads SMS (SMS Retriever), make sure the manual input path still works, since that is what the test exercises.

Parallel workers

Detox can run several simulators with Jest workers (--maxWorkers). Each test generates its own number, so workers never read each other's codes and no inbox cleanup is needed between tests.

Common pitfalls

• Mocking in the app bundle. Don't stub the API call in the app; let the real backend send through the provider so the test covers the actual path.
• Formatted phone inputs. If the input formats as you type or a country picker supplies +1, query the E.164 number the backend actually sent.
• Detox synchronization timeouts. waitForCode runs outside the app, so Detox's idle tracking is not involved; set a Jest test timeout above the helper timeout (for example 120 s in your Jest config).
• Release builds pointing to production. Build the e2e configuration against the staging backend.

FAQ

Related guides

• Test SMS OTP verification in AppiumWebdriverIO and Python on Android and iOS.
• Test SMS OTP verification in MaestroYAML flows with a runScript that reads the code.
• Test SMS OTP in PlaywrightFixtures, unique numbers, parallel workers.