Before you run the SMS OTP testing checklist

Get these details from the spec or the developers, because they're what you test against. If nobody can tell you, that's your first bug report.

• Code length and whether it's digits only
• Code lifetime in seconds
• Wrong attempts allowed before the code is burned
• Resend cooldown, and the maximum sends per number, per account and per IP address
• Whether a new code cancels the previous one
• Where codes go in test environments: a stub outbox, the provider's test mode or a log

Make sure test environments can't text real strangers. Reserved fictional numbers, such as 555-0100 to 555-0199 in North American format, are a cheap safeguard for stubbed tests.

Happy path

• The code arrives in the expected time.
• The message names the product, shows the code, states the expiry, says not to share it and is in the user's language.
• The correct code is accepted and the user lands in the right place.
• The same code is rejected the second time.
• Pasting the code works, including with spaces around it.
• The phone's keyboard offers the code from the incoming text, where the platform supports it.
• Codes starting with 0 work: 012345 must not become 12345.

Wrong codes

• A wrong code shows a clear error without hinting which digits were right.
• After the allowed number of wrong attempts, the code stops working even if the correct one is then entered.
• Letters, symbols and the wrong number of digits are handled without a crash.
• A code sent to one number or account can't verify a different one.

Expiry

• A code entered just before the stated lifetime is accepted.
• A code entered just after it is rejected, with a message that says what to do next.
• The lifetime in the SMS text matches what the server enforces.

Rather than waiting real minutes, ask for a configurable lifetime in staging or clock control in automated tests.

Resend

• The resend button is disabled during the cooldown, with a visible countdown.
• Reloading the page doesn't reset the cooldown.
• A double click sends one SMS, not two.
• After a resend, the old code behaves as specified, usually rejected.
• Editing the phone number restarts the flow and sends to the new number only.

Rate limits

• Sends per number are capped, and the error explains when to try again.
• Sends per account and per IP address are capped too.
• Requests to many different numbers from one source are limited, which blocks SMS pumping: bots triggering texts to run up your bill.
• Limits reset after the window ends.
• The response doesn't reveal whether a number is registered.

Phone number formats and locales

• The country selector defaults sensibly and is searchable.
• International format with + is accepted, as is the local format with a leading 0 for countries that use one, such as the UK or the Netherlands.
• A leading 0 typed after the country code is handled: corrected or clearly rejected.
• Spaces, dashes, brackets and pasted numbers are cleaned up; too short or too long ones get a helpful error.
• Landline or VoIP numbers are handled as the policy says, with a clear message.
• Translated messages stay within the expected number of SMS parts. One character outside the basic GSM-7 alphabet cuts a single message from 160 characters to 70.
• Right-to-left languages display correctly on the code screen.
• Error messages and the countdown are announced by screen readers, not only shown visually.

Security and privacy

• The code never appears in an API response, a URL, analytics, browser storage, server logs or error trackers.
• Verification happens on the server; changing the response in the browser doesn't skip the step.
• The code is tied to the sign-in session that requested it.
• Brute-force attempts spread across several sessions still hit a limit.

Real-network check

Stubs prove the logic, not delivery. Before release, test on real phones:

• Each country you launch in, ideally on more than one carrier.
• Delivery time is acceptable on a normal mobile connection.
• The sender name or number shows as expected in each country.
• Messages aren't filtered or mangled, and long ones reassemble.
• The full flow works on both major mobile platforms.

For a quick manual check in several countries, the free public numbers on Temp SMS show incoming texts on a web page, with US, Canadian, UK, Dutch, Finnish, Swedish and Belgian numbers listed. Use them only with test accounts and test data: every message is visible to anyone, the numbers are shared and retired over time, and they must never be used for banking, a main email account or two-factor authentication.

FAQ

How do you test OTP without a real phone? Use a stubbed SMS provider or the provider's test mode, and read codes from the stub's outbox. Keep real phones for the final delivery check.

What should be tested in SMS OTP verification? Correct and wrong codes, expiry, resend, rate limits, number formats, localisation, security leaks and real delivery.

How do I test OTP expiry without waiting? Ask for a shorter lifetime in staging or for clock control in automated tests, then test just before and just after the limit.

Should QA test OTP with real phone numbers? Yes, for the final check. Stubs can't show carrier filtering, delivery delays or how the sender appears on a real phone.

More on SMS verification for developers:

• Testing SMS OTP in Python with pytest
• Testing SMS OTP with Playwright
• SMS character counter (GSM-7 vs UCS-2)

The code under test

A small service that sends a six-digit code, stores only an HMAC of it, accepts it once, burns it after five wrong guesses or five minutes, and allows three codes per number per hour:

# otp.py
import hashlib
import hmac
import secrets
import time
from dataclasses import dataclass
from typing import Protocol


class SmsSender(Protocol):
    def send(self, to: str, body: str) -> None: ...


class RateLimited(Exception):
    pass


@dataclass
class _Pending:
    code_hash: str
    expires_at: float
    attempts: int = 0


class OtpService:
    CODE_TTL = 300      # seconds a code stays valid
    MAX_ATTEMPTS = 5    # wrong guesses before the code is burned
    MAX_SENDS = 3       # codes per number per window
    SEND_WINDOW = 3600  # seconds

    def __init__(self, sender: SmsSender, secret: bytes):
        self._sender = sender
        self._secret = secret
        self._pending: dict[str, _Pending] = {}
        self._sends: dict[str, list[float]] = {}

    def _hash(self, phone: str, code: str) -> str:
        msg = f"{phone}:{code}".encode()
        return hmac.new(self._secret, msg, hashlib.sha256).hexdigest()

    def request_code(self, phone: str) -> None:
        now = time.time()
        recent = [t for t in self._sends.get(phone, []) if now - t < self.SEND_WINDOW]
        if len(recent) >= self.MAX_SENDS:
            raise RateLimited(phone)

        code = f"{secrets.randbelow(10**6):06d}"
        self._sender.send(phone, f"Your Example code is {code}. It expires in 5 minutes.")
        # Only store the code once the provider accepted the message.
        self._pending[phone] = _Pending(self._hash(phone, code), now + self.CODE_TTL)
        self._sends[phone] = recent + [now]

    def verify(self, phone: str, code: str) -> bool:
        pending = self._pending.get(phone)
        if pending is None or time.time() >= pending.expires_at:
            self._pending.pop(phone, None)
            return False

        pending.attempts += 1
        if pending.attempts > self.MAX_ATTEMPTS:
            del self._pending[phone]
            return False

        if hmac.compare_digest(pending.code_hash, self._hash(phone, code)):
            del self._pending[phone]  # single use
            return True
        return False

Two choices make it testable:

• The sender is injected. Anything with a send(to, body) method will do, so tests never call a real provider or need a network.
• The clock is time.time(). time-machine doesn't move time.monotonic(), so expiry uses wall-clock timestamps, which you'd store in a database anyway.

A fake provider and an outbox fixture

# tests/conftest.py
import re

import pytest

from otp import OtpService


class FakeSms:
    """Stands in for the SMS provider and keeps every message."""

    def __init__(self):
        self.outbox: list[tuple[str, str]] = []

    def send(self, to: str, body: str) -> None:
        self.outbox.append((to, body))

    def last_code(self, to: str) -> str:
        for number, body in reversed(self.outbox):
            if number == to:
                return re.search(r"\b(\d{6})\b", body).group(1)
        raise AssertionError(f"no SMS was sent to {to}")


@pytest.fixture
def sms():
    return FakeSms()


@pytest.fixture
def otp(sms):
    return OtpService(sender=sms, secret=b"test-only-secret")

Plus a pytest.ini so the tests can import otp from the project root:

[pytest]
pythonpath = .
testpaths = tests

Reading the code from the outbox, rather than patching the random generator, tests the real path from generation to message text.

Testing SMS OTP in Python with pytest: the core cases

# tests/test_otp.py
import datetime as dt
import re
from unittest.mock import Mock

import pytest
from freezegun import freeze_time

from otp import OtpService, RateLimited

PHONE = "+12015550123"
START = dt.datetime(2026, 1, 1, 12, 0, tzinfo=dt.timezone.utc)


def test_sends_one_sms_with_a_six_digit_code(otp, sms):
    otp.request_code(PHONE)

    assert len(sms.outbox) == 1
    to, body = sms.outbox[0]
    assert to == PHONE
    assert body.startswith("Your Example code is ")
    assert len(sms.last_code(PHONE)) == 6


def test_correct_code_works_once(otp, sms):
    otp.request_code(PHONE)
    code = sms.last_code(PHONE)

    assert otp.verify(PHONE, code) is True
    assert otp.verify(PHONE, code) is False


def test_code_is_burned_after_too_many_wrong_guesses(otp, sms):
    otp.request_code(PHONE)
    code = sms.last_code(PHONE)
    wrong = f"{(int(code) + 1) % 10**6:06d}"

    for _ in range(OtpService.MAX_ATTEMPTS):
        assert otp.verify(PHONE, wrong) is False

    assert otp.verify(PHONE, code) is False

The wrong guess is derived from the real code, so it can never be right by accident. The numbers are in the fictional 555-0100 to 555-0199 range, so a misconfigured test can't text a real person.

Code expiry with time-machine and freezegun

time-machine ships a time_machine pytest fixture. move_to(..., tick=False) stops the clock and shift() moves it forward:

@pytest.mark.parametrize(("elapsed", "accepted"), [(299, True), (300, False)])
def test_code_expiry(otp, sms, time_machine, elapsed, accepted):
    time_machine.move_to(START, tick=False)
    otp.request_code(PHONE)

    time_machine.shift(elapsed)

    assert otp.verify(PHONE, sms.last_code(PHONE)) is accepted

Testing 299 and 300 seconds pins the boundary: change >= to > in verify() and the 300-second case fails.

The same check with freezegun, if your project already uses it:

def test_code_expiry_with_freezegun(otp, sms):
    with freeze_time("2026-01-01 12:00:00") as frozen:
        otp.request_code(PHONE)
        frozen.tick(301)
        assert otp.verify(PHONE, sms.last_code(PHONE)) is False

Rate limits without sleeping

def test_fourth_code_within_an_hour_is_refused(otp, sms, time_machine):
    time_machine.move_to(START, tick=False)
    for _ in range(3):
        otp.request_code(PHONE)
        time_machine.shift(60)

    with pytest.raises(RateLimited):
        otp.request_code(PHONE)
    assert len(sms.outbox) == 3


def test_rate_limit_resets_after_the_window(otp, sms, time_machine):
    time_machine.move_to(START, tick=False)
    for _ in range(3):
        otp.request_code(PHONE)

    time_machine.shift(3600)
    otp.request_code(PHONE)

    assert len(sms.outbox) == 4

Moving the clock instead of sleeping keeps both tests instant.

Provider failures with Mock

When the provider times out, the user must not end up with a code that works but never arrived:

def test_provider_failure_leaves_no_usable_code():
    sender = Mock()
    sender.send.side_effect = TimeoutError("provider timed out")
    service = OtpService(sender=sender, secret=b"test-only-secret")

    with pytest.raises(TimeoutError):
        service.request_code(PHONE)

    sender.send.assert_called_once()
    code = re.search(r"\d{6}", sender.send.call_args.args[1]).group()
    assert service.verify(PHONE, code) is False

Running it

python3 -m venv .venv
source .venv/bin/activate
pip install pytest time-machine freezegun
pytest -q

.........                                                                [100%]
9 passed in 0.05s

What unit tests can't tell you

Fakes prove your logic, not delivery. Before launch, send real codes to real numbers in each country you serve. For a quick manual check, free public numbers on Temp SMS show incoming texts on a web page with no account. Anyone can read them and the numbers are retired over time, so use them only for throwaway test accounts, never banking, a main email or two-factor authentication.

FAQ

Should I mock the SMS provider's SDK or my own wrapper? Your own wrapper. A one-method send(to, body) interface is easy to fake, and the SDK call can be covered by a single integration test.

Should I use time-machine or freezegun? Either works for this. time-machine is a C extension with a built-in pytest fixture; freezegun is the older library and also moves time.monotonic().

How do I test OTP expiry without waiting? Freeze the clock, request a code, move the clock past the expiry time and verify. No time.sleep() needed.

More on SMS verification for developers:

• Testing SMS OTP with Playwright: stubs, fake timers and rate limits
• How to build a secure SMS OTP verification endpoint in Node.js

Where the stub belongs

Playwright drives the browser, but your backend sends the SMS. page.route() only intercepts requests the browser makes, so it can't see the server-to-provider call. The stub goes on the server:

• Put the provider behind a small SmsSender interface.
• In the test environment, bind it to an in-memory outbox that records { to, body }.
• Add a test-only endpoint, e.g. GET /__test/sms?to=... (and DELETE to reset that number's outbox and rate-limit counters). Mount it only when NODE_ENV === 'test' and require a token.

Skip the fixed 000000 code: reading the real generated code exercises your generation and expiry logic.

Helpers: a safe number and a polled code

// tests/helpers/otp.ts
import { expect, type APIRequestContext, type TestInfo } from '@playwright/test';

const headers = { 'x-test-token': process.env.TEST_TOKEN ?? '' };

// 555-0100..0199 is reserved for fiction, so a stub mistake never texts a real person.
export function testPhone(testInfo: TestInfo): string {
  return `+1202555${String(100 + testInfo.parallelIndex).padStart(4, '0')}`;
}

export async function resetPhone(request: APIRequestContext, to: string): Promise<void> {
  await request.delete('/__test/sms', { params: { to }, headers });
}

export async function latestCode(request: APIRequestContext, to: string): Promise<string> {
  let code = '';
  await expect.poll(async () => {
    const res = await request.get('/__test/sms', { params: { to }, headers });
    if (!res.ok()) return '';
    const { messages } = (await res.json()) as { messages: { body: string }[] };
    code = messages.at(-1)?.body.match(/\b(\d{6})\b/)?.[1] ?? '';
    return code;
  }, { timeout: 10_000 }).not.toBe('');
  return code;
}

One number per parallel worker plus a reset in beforeEach keeps tests from tripping each other's limits.

The happy path

// tests/otp.spec.ts
import { test, expect } from '@playwright/test';
import { latestCode, resetPhone, testPhone } from './helpers/otp';

test.beforeEach(async ({ request }, testInfo) => {
  await resetPhone(request, testPhone(testInfo));
});

test('signs up with the code from the outbox', async ({ page, request }, testInfo) => {
  const phone = testPhone(testInfo);
  await page.goto('/signup');
  await page.fill('#phone', phone);
  await page.getByRole('button', { name: 'Send code' }).click();
  await expect(page.getByText('We sent a code')).toBeVisible();

  await page.fill('#otp', await latestCode(request, phone));
  await page.getByRole('button', { name: 'Verify' }).click();
  await expect(page.getByText('Your account is ready')).toBeVisible();
});

Fake timers for the resend countdown

Don't wait 30 real seconds for a "Resend" button. Install the fake clock before goto, then advance it:

test('resend unlocks after the cooldown', async ({ page }, testInfo) => {
  await page.clock.install();
  await page.goto('/signup');
  await page.fill('#phone', testPhone(testInfo));
  await page.getByRole('button', { name: 'Send code' }).click();

  const resend = page.getByRole('button', { name: /resend/i });
  await expect(resend).toBeDisabled();
  await page.clock.runFor(30_000);
  await expect(resend).toBeEnabled();
});

runFor fires every timer due in that window, which suits a countdown built on repeated setTimeout calls. The Clock API docs cover fastForward, pauseAt and the rest.

One limit: page.clock only changes time in the browser. Server-side code expiry follows the server's clock, so inject a clock into your backend or add a test-only way to age a code.

Asserting rate limits

Test the policy at the API level, where it's enforced:

test('code requests are rate-limited per number', async ({ request }, testInfo) => {
  const phone = testPhone(testInfo);
  const statuses: number[] = [];
  for (let i = 0; i < 4; i++) {
    const res = await request.post('/api/otp/send', { data: { phone } });
    statuses.push(res.status());
  }
  expect(statuses).toEqual([200, 200, 200, 429]); // our policy: 3 per window
});

Then test the UI's reaction. Here page.route() is the right tool, because the browser makes this request:

test('explains the limit when the API returns 429', async ({ page }) => {
  await page.route('**/api/otp/send', (route) =>
    route.fulfill({ status: 429, json: { error: 'too_many_requests' } }),
  );
  await page.goto('/signup');
  await page.fill('#phone', '+12025550123');
  await page.getByRole('button', { name: 'Send code' }).click();
  await expect(page.getByText(/too many attempts/i)).toBeVisible();
});

Keep codes and secrets out of logs

• No real provider key in CI. With the outbox bound, there's nothing to leak.
• Treat traces as sensitive. trace: 'retain-on-failure' is a good default, but a trace holds DOM snapshots, network bodies and the action log, including values passed to fill. Keep artifact retention short and never publish them from a public repository.
• Don't log codes or tokens. Reporters capture stdout.
• Mask screenshots you take yourself: await page.screenshot({ path: 'otp.png', mask: [page.locator('#otp')] }).
• Prove the test endpoint is absent in production with a smoke test that expects /__test/sms to return 404.

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: { baseURL: process.env.BASE_URL ?? 'http://localhost:3000', trace: 'retain-on-failure' },
  webServer: { command: 'npm run start:test', url: 'http://localhost:3000' }, // app with the outbox sender
});

What stubs can't tell you

All of this proves your logic, not that a carrier delivers your message: sender rules, encoding and filtering differ by country. Before launch, do a short manual pass on staging with real numbers. Free public numbers on Temp SMS show incoming texts on a web page with no account, which makes that check quick. Anyone can read those messages, so use them only for disposable test accounts.

FAQ

Can Playwright intercept the SMS my backend sends? No. page.route() only sees browser requests. Stub the provider on the server and read the code through a test-only endpoint.

Does page.clock make my OTP expire sooner? Only in the browser. Server-side expiry needs a controllable server clock or a test hook.

Should I use a fixed test code like 000000? It skips your real generation and verification path, and it's risky if the flag ever reaches production.

More on SMS verification for developers:

• How to build a secure SMS OTP verification endpoint in Node.js
• How to test SMS OTP verification without a real phone number