How to Automate OTP in Playwright: Real SMS Codes via Webhook in GitHub Actions

✘ [chromium] › tests/signup.spec.ts:4:5 › sign-up with SMS code (30.0s) Test timeout of 30000ms exceeded. 

fixture -> POST /activations (buy a number) test -> types it, clicks "Send code"; your app sends the SMS HeroSMS -> POST sms-incoming -> tunnel -> webhook-server.ts server -> writes .otp-inbox/<activationId>.json fixture -> waitForCode() resolves; the test submits the code teardown -> finish (code used) or DELETE (no code, refund) 

// tests/herosms.ts const API = 'https://hero-sms.com/api/v1'; export interface Activation { id: number; phone: number; // digits only, no "+" countryPhoneCode: number; expiredAt: string; } export type Offer = { counts: { total: number } }; type ErrorBody = { title?: string; details?: string; info?: Record<string, unknown> }; export class HeroSmsError extends Error { status: number; title: string; info?: Record<string, unknown>; constructor(status: number, body: ErrorBody) { super(`HTTP ${status} ${body.title ?? ''}: ${body.details ?? ''}`); this.status = status; this.title = body.title ?? ''; this.info = body.info; } } export async function call<T>(method: string, path: string, body?: unknown): Promise<T | undefined> { 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}`, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(15_000), // keep teardown from hanging }); const text = await res.text(); if (res.status >= 400) { let err: ErrorBody = {}; try { err = JSON.parse(text) ?? {}; } catch { /* not JSON */ } throw new HeroSmsError(res.status, err); } return text ? (JSON.parse(text) as T) : undefined; // 204 -> undefined } export async function checkOffer(service: string, country: number): Promise<Offer | null> { const qs = new URLSearchParams({ services: service, countries: String(country) }); try { const res = await call<{ data?: Record<string, Record<string, Offer>> }>('GET', `/activations/offers/sms?${qs}`); return res?.data?.[service]?.[String(country)] ?? null; } catch (e) { if (e instanceof HeroSmsError && e.status === 404) return null; // OFFER_NOT_FOUND throw e; } } export async function buyNumber(service: string, country: number, maxPrice?: number): Promise<Activation> { const res = await call<{ data: Activation[] }>('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]; } export const finishActivation = (id: number) => call('POST', `/activations/${id}/finish`); // no refund export const cancelActivation = (id: number) => call('DELETE', `/activations/${id}`); // refund const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)); // Never throws: cleanup must not mask the test failure. export async function release(a: Activation, gotOtp: boolean, boughtAt: number): Promise<void> { try { if (gotOtp) { await finishActivation(a.id); return; } try { await cancelActivation(a.id); } catch (e) { if (!(e instanceof HeroSmsError)) throw e; if (e.title === 'EARLY_CANCEL_DENIED') { const minSec = Number(e.info?.minActivationTime) || 120; await sleep(Math.max(0, boughtAt + minSec * 1000 + 5_000 - Date.now())); try { await cancelActivation(a.id); } catch (e2) { // The SMS may arrive during the wait: close the activation instead of leaving it open if (e2 instanceof HeroSmsError && e2.title === 'OTP_RECEIVED') await finishActivation(a.id); else throw e2; } } else if (e.title === 'OTP_RECEIVED') { await finishActivation(a.id); // late SMS } else { throw e; } } } catch (e) { const what = e instanceof HeroSmsError ? `HTTP ${e.status} ${e.title}` : (e as Error).name; console.warn(`cleanup ${a.id}: ${what}`); } } 

// tests/inbox.ts import fs from 'node:fs'; import path from 'node:path'; // sms-incoming body (also has phoneFrom, service, country) export interface SmsWebhookPayload { activationId: number; text: string | null; code?: string | null; receivedAt: string; } const INBOX_DIR = process.env.OTP_INBOX_DIR ?? path.resolve('.otp-inbox'); // sanitize: the id comes from outside const inboxFile = (id: number | string) => path.join(INBOX_DIR, `${String(id).replace(/[^\w-]/g, '_')}.json`); function readSms(file: string): SmsWebhookPayload | null { try { return JSON.parse(fs.readFileSync(file, 'utf8')) as SmsWebhookPayload; } catch { return null; // not there yet } } export function saveSms(p: SmsWebhookPayload): void { fs.mkdirSync(INBOX_DIR, { recursive: true }); const file = inboxFile(p.activationId); const prev = readSms(file); if (prev && prev.receivedAt > p.receivedAt) return; // retries repeat, resends are newer const tmp = `${file}.${process.pid}.tmp`; fs.writeFileSync(tmp, JSON.stringify(p)); fs.renameSync(tmp, file); // atomic: a reader never sees half a file } export const extractCode = (p: SmsWebhookPayload) => p.code || p.text?.match(/\b\d{4,8}\b/)?.[0]; export function waitForOtp(id: number, timeoutMs: number): Promise<string> { fs.mkdirSync(INBOX_DIR, { recursive: true }); const file = inboxFile(id); return new Promise((resolve, reject) => { const watcher = fs.watch(INBOX_DIR, (_event, name) => { if (name === path.basename(file)) tryRead(); }); const timer = setTimeout(() => { watcher.close(); reject(new Error(`No OTP for activation ${id} after ${timeoutMs} ms`)); }, timeoutMs); function tryRead() { const sms = readSms(file); const code = sms ? extractCode(sms) : undefined; if (!code) return; watcher.close(); clearTimeout(timer); resolve(code); } tryRead(); // the SMS may already be there }); } 

// tests/webhook-server.ts import http from 'node:http'; import { saveSms, type SmsWebhookPayload } from './inbox'; const PORT = Number(process.env.WEBHOOK_PORT ?? 3999); // pick a port your app doesn't use const HOOK_PATH = process.env.WEBHOOK_PATH || '/hooks/herosms'; // use a long random path const MAX_BODY = 64 * 1024; http.createServer((req, res) => { if (req.method === 'GET' && req.url === '/health') { res.writeHead(200).end('ok'); return; } if (req.method !== 'POST' || req.url !== HOOK_PATH) { res.writeHead(404).end(); return; } let body = ''; req.setEncoding('utf8'); // non-Latin SMS text can span chunks req.on('data', (chunk: string) => { body += chunk; if (body.length > MAX_BODY) req.destroy(); }); req.on('end', () => { try { const p = JSON.parse(body) as SmsWebhookPayload; if (Number.isFinite(p?.activationId)) saveSms(p); } catch (err) { // name only: the body holds SMS text console.warn('[webhook] bad payload:', err instanceof Error ? err.name : 'unknown'); } res.writeHead(200, { 'Content-Type': 'application/json' }).end('{}'); // always 200, fast }); }).listen(PORT, '127.0.0.1'); 

// tests/otp-fixture.ts import { test as base, expect } from '@playwright/test'; import { buyNumber, checkOffer, release } from './herosms'; import { waitForOtp } from './inbox'; export type Otp = { phone: string; activationId: number; waitForCode: (timeoutMs?: number) => Promise<string>; }; export const te...