Pitch: como testar OTP por SMS no Postman e no Newman (CI) com número real
Transparência: Trabalho com a HeroSMS, o provedor de números virtuais usado nos exemplos de teste de OTP por SMS abaixo. Texto escrito com ferramentas de IA; código e endpoints conferidos com a referência da API da HeroSMS e com a documentação do Postman.
Quem testa login no Postman conhece o ponto em que a collection trava: o cadastro manda um código de verificação por SMS e alguém precisa ler no celular e colar em {{otp_code}}. No Newman ou no CI não tem quem cole, então o passo do OTP fica de fora.
Abaixo, uma collection que faz esse passo sozinha: aluga um número real numa API de SMS, dispara o envio do código pelo seu app, consulta a API até o código chegar (com prazo), verifica o código no app e libera o número no final, passe ou falhe o teste. Ela roda no Collection Runner, no Newman e num job agendado do GitHub Actions.
O Postman consegue ler um OTP por SMS?
Não: o Postman não tem chip. O caminho é alugar um número numa API de SMS, fazer o seu app enviar o código para ele e consultar a API por script até o código chegar, salvando o valor numa variável.
Mock, número de teste ou número real: quando usar cada um
- Mock ou envio de SMS stubado: prova a lógica do app. De graça, em todo PR.
- Credenciais ou números de teste do provedor de SMS: provam a chamada ao provedor. Também em todo PR.
- Número real alugado: prova que um SMS de verdade chega no país onde você vai lançar e que a sua API aceita o código. É pago por número, então fica para um job noturno ou para antes do release, nunca em todo commit.
O que você precisa
- O Collection Runner, ou o Newman 6.2.3 com Node 16 ou mais novo. Fixe a versão: o
pm.execution.setNextRequestchegou no postman-sandbox 4.6.0 (março de 2024), e um Newman 6.x mais antigo pode não ter. - Uma chave da API da HeroSMS e saldo. Você compra uma ativação: um número reservado para um serviço em um país por cerca de 20 minutos (o fim exato vem em
expiredAt). - Um environment com estas variáveis:
| Variável | Exemplo | Observação |
|---|---|---|
herosms_api_key | <sua chave da API> | Só no valor local (Local value, antigo Current value); no CI vem de um secret |
otp_service | <código do serviço> | 2 a 4 letras; para o seu app, ot ("Any other") |
otp_country | <ID do país> | Um inteiro |
otp_max_price | vazio | Teto opcional de preço por número |
app_url | https://staging.example.com | O seu app em staging |
Os códigos de serviço e os IDs de país estão na referência da API, e GET /activations/offers/sms sem filtros também devolve os dois.
A chave não vai em variável de collection, que é exportada junto, nem no valor compartilhado (Shared value, antigo Initial value) do environment, que sincroniza com a nuvem do Postman. E o Newman não lê o cofre local (Vault) do Postman.
A collection: seis requests, nesta ordem
Quando um script não chama setNextRequest, o runner segue para o próximo request da lista, então a ordem importa. O header Authorization: ApiKey {{herosms_api_key}} vai só nos quatro requests da HeroSMS; no nível da collection, ele mandaria a sua chave também para a sua própria API. Requests com corpo levam Content-Type: application/json.
| # | Nome | Request | Corpo |
|---|---|---|---|
| 1 | Buy number | POST https://hero-sms.com/api/v1/activations | {{buy_body}} |
| 2 | Send code (app) | POST {{app_url}}/api/otp/send | {"phone": "{{phone}}"} |
| 3 | Poll OTP | GET https://hero-sms.com/api/v1/activations/{{activation_id}}/otp/last | nenhum |
| 4 | Verify code (app) | POST {{app_url}}/api/otp/verify | {"phone": "{{phone}}", "code": "{{otp_code}}"} |
| 5 | Finish number | POST https://hero-sms.com/api/v1/activations/{{activation_id}}/finish | nenhum |
| 6 | Cancel number | DELETE https://hero-sms.com/api/v1/activations/{{activation_id}} | nenhum |
Os requests 2 e 4 são placeholders para o seu app. O estado de cada execução fica em variáveis de collection, e a collection não guarda mais nada nelas, então pm.collectionVariables.clear() zera tudo sem risco. Os scripts pulam entre requests pelo nome: se renomear um, atualize as chamadas.
1. Buy number
// Buy number > Scripts > Pre-request
pm.collectionVariables.clear(); // nada sobrando de uma execução que caiu
const service = pm.variables.get('otp_service');
const country = parseInt(pm.variables.get('otp_country'), 10);
const cap = pm.variables.get('otp_max_price');
const maxPrice = cap ? Number(cap) : undefined;
if (!service || !Number.isInteger(country) || Number.isNaN(maxPrice)) {
pm.test('variáveis do OTP definidas', () => {
throw new Error('defina otp_service e um otp_country inteiro; otp_max_price precisa ser um número');
});
pm.execution.setNextRequest(null); // tem que vir antes: o skipRequest encerra o script na hora
pm.execution.skipRequest(); // não compra com um corpo quebrado
} else {
pm.variables.set('buy_body', JSON.stringify({
service,
country,
amount: 1,
verificationType: 'sms',
...(maxPrice ? { maxPrice } : {}),
}));
}
// Buy number > Scripts > Post-response
const v = pm.collectionVariables;
let body = {};
try { body = pm.response.json() || {}; } catch (e) { /* não é JSON */ }
const a = (body.data || [])[0];
pm.test('número alugado', () => {
pm.expect(pm.response.code, `${body.title || ''} ${body.details || ''}`).to.be.below(400);
pm.expect(a, 'data[0]').to.be.an('object');
});
if (pm.response.code < 400 && a) {
v.set('activation_id', a.id);
v.set('phone', '+' + a.phone); // o phone vem só com dígitos, sem '+'
v.set('bought_at', Date.now());
} else {
pm.execution.setNextRequest(null); // nada comprado, nada para liberar
}
Sem a checagem, um otp_country vazio vira NaN, o JSON.stringify manda null e a compra sai assim mesmo. Se o formulário pede o número nacional, tire do phone o prefixo countryPhoneCode, que também vem na resposta da compra.
2. Send code (app)
// Send code (app) > Scripts > Post-response
const ok = pm.response.code >= 200 && pm.response.code < 300;
pm.test('app enviou o código', () => pm.expect(ok, `HTTP ${pm.response.code}`).to.be.true);
if (ok) {
// 2 minutos de polling, bem dentro da ativação de ~20 minutos
pm.collectionVariables.set('poll_deadline', Date.now() + 120000);
} else {
pm.execution.setNextRequest('Cancel number'); // não vai chegar SMS: reembolso
}
3. Poll OTP: loop com setNextRequest até o código chegar
O request 3 consulta otp/last e chama a si mesmo com pm.execution.setNextRequest até o código chegar ou o prazo acabar. A resposta traz smsCode (o código) e smsText (a mensagem completa), e qualquer um dos dois pode vir null.
// Poll OTP > Scripts > Post-response
const v = pm.collectionVariables;
const CLOSED = ['ACTIVATION_NOT_ACTIVE', 'CANCELED', 'FINISHED', 'REFUNDED'];
const status = pm.response.code;
let body = {};
try { body = pm.response.json() || {}; } catch (e) { /* 204 ou não é JSON */ }
const otp = body.data || {};
const code = otp.smsCode || ((otp.smsText || '').match(/\b\d{4,8}\b/) || [])[0];
const left = Number(v.get('poll_deadline')) - Date.now();
// sem status = request que caiu ou --timeout-request: tenta de novo
const notYet = !status || status < 400
|| ([400, 404].includes(status) && !CLOSED.includes(body.title));
if (code) {
v.set('otp_code', String(code));
pm.execution.setNextRequest('Verify code (app)');
} else if (otp.smsText) {
pm.test('SMS contém um código de 4 a 8 dígitos', () => {
throw new Error('o SMS chegou sem código: ajuste a regex ao seu template');
});
pm.execution.setNextRequest('Finish number'); // chegou SMS, então sem reembolso
} else if ((notYet || status === 429) && left > 0) {
const delay = Number(v.get('poll_delay')) || 2000; // backoff de 2 s até 10 s
const wait = status === 429
? (Number(pm.response.headers.get('Retry-After')) || 5) * 1000
: delay;
v.set('poll_delay', Math.min(Math.round(delay * 1.5), 10000));
setTimeout(() => {}, Math.min(wait, left)); // o script termina quando este timer dispara
pm.execution.setNextRequest(pm.info.requestId); // consulta de novo
} else {
pm.test('SMS com código chegou a tempo', () => {
throw new Error(`sem código: HTTP ${status} ${body.title || ''}`);
});
pm.execution.setNextRequest('Cancel number');
}
O sandbox do Postman mantém o script vivo enquanto há timers pendentes, então o setTimeout vazio no fim atrasa só o próximo request.
- A referência não documenta a resposta antes do primeiro SMS, então 400, 404 e
datavazio contam como "ainda não", a menos que otitlediga que a ativação foi encerrada. Um 404 por ID errado vai parecer timeout. - O
Retry-Afterno 429 só está documentado no endpoint de ofertas, daí o fallback de 5 segundos. - O
setNextRequestnão tem limite de loop, por isso o prazo. Funciona no Collection Runner, no Newman e no Postman CLI, mas não quando você clica em Send num request isolado.
4 e 5. Verify code e Finish number
// Verify code (app) > Scripts > Post-response
pm.test('app aceitou o código real', () => {
pm.expect(pm.response.code).to.equal(200);
});
// passando ou falhando, o SMS chegou: o próximo request na ordem é o Finish number
// Finish number > Scripts > Post-response
pm.test('número encerrado', () => pm.expect(pm.response.code).to.be.below(400));
pm.collectionVariables.clear();
pm.execution.setNextRequest(null); // para aqui: o Cancel number é para o caminho sem SMS
6. Cancel number
Só roda nos caminhos de falha: cancela a ativação, o que devolve o valor ao saldo.
// Cancel number > Scripts > Post-response
const v = pm.collectionVariables;
let body = {};
try { body = pm.response.json() || {}; } catch (e) { /* não é JSON */ }
const tries = Number(v.get('cancel_tries')) || 0;
if (body.title === 'OTP_RECEIVED') {
pm.execution.setNextRequest('Finish number'); // o SMS chegou atrasado: encerra em vez de cancelar
} else if (body.title === 'EARLY_CANCEL_DENIED' && tries < 1) {
const minSec = Number(body.info && body.info.minActivationTime) || 120;
const wait = Number(v.get('bought_at')) + minSec * 1000 + 5000 - Date.now();
v.set('cancel_tries', tries + 1);
setTimeout(() => {}, Math.max(0, wait)); // espera passar a janela do cancelamento antecipado
pm.execution.setNextRequest(pm.info.requestId); // e tenta mais uma vez
} else {
if (!(pm.response.code < 400)) { // erro HTTP ou request que caiu
console.error(`cancelamento ${v.get('activation_id')}: HTTP ${pm.response.code} ${body.title || ''}`);
}
pm.collectionVariables.clear();
pm.execution.setNextRequest(null);
}
- Nos primeiros minutos a API recusa o cancelamento (
EARLY_CANCEL_DENIED, cominfo.minActivationTime; cerca de 2 minutos nos exemplos da referência). O script espera e tenta de novo. - Com SMS atrasado, a API responde
OTP_RECEIVEDe o script encerra pelo Finish, sem reembolso. - Se o runner morrer, número sem SMS é reembolsado no saldo, e
GET /activationslista o que ficou aberto.
Rodando a collection no Newman e no GitHub Actions (CI)
Exporte a collection como JSON v2.1 e rode:
newman run otp-real-sms.postman_collection.json -e local.postman_environment.json \
-r cli,junit --reporter-junit-export results/otp-real-sms.xml \
--timeout-request 15000 --timeout-script 180000
- Abra o environment exportado antes da primeira execução: se a chave estiver nele, está em texto puro. Ponha o arquivo no
.gitignore, ou deixe a chave fora dele e passe--env-var "herosms_api_key=$HEROSMS_API_KEY"só na sua máquina. - O
--timeout-scriptprecisa ser maior que osetTimeoutmais longo, aqui a espera do cancelamento. - Nada de
--bailnem de--timeoutcurto, que podem pular o Finish e o Cancel. Nada de-nacima de 1: cada iteração compra um número. - Teste que falha faz o Newman sair com código 1, e o job falha.
A documentação do Newman avisa que ele não vai mais receber atualizações nem correções e recomenda migrar para o Postman CLI, que aceita flags parecidas (postman collection run ...).
No GitHub Actions, o teste com número real roda agendado, não a cada push:
# .github/workflows/otp-real-sms.yml
name: otp-real-sms
on:
schedule:
- cron: '0 4 * * 1-5' # 04:00 UTC em dias úteis; cada execução compra um número
workflow_dispatch:
concurrency:
group: otp-real-sms
cancel-in-progress: false # uma execução cancelada nunca chega ao Cancel number
jobs:
newman:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
- run: npm install -g newman@6.2.3
- name: Grava o arquivo do environment (a chave fica fora da linha de comando)
env:
HEROSMS_API_KEY: ${{ secrets.HEROSMS_API_KEY }}
run: |
node -e 'require("fs").writeFileSync("ci.postman_environment.json",
JSON.stringify({ values: [{ key: "herosms_api_key",
value: process.env.HEROSMS_API_KEY, enabled: true }] }), { mode: 0o600 })'
- name: Roda a collection com SMS real
env:
OTP_SERVICE: ${{ vars.OTP_SERVICE }}
OTP_COUNTRY: ${{ vars.OTP_COUNTRY }}
OTP_MAX_PRICE: ${{ vars.OTP_MAX_PRICE }}
APP_URL: ${{ vars.APP_URL }}
run: |
newman run postman/otp-real-sms.postman_collection.json \
-e ci.postman_environment.json \
--env-var "otp_service=$OTP_SERVICE" \
--env-var "otp_country=$OTP_COUNTRY" \
--env-var "otp_max_price=$OTP_MAX_PRICE" \
--env-var "app_url=$APP_URL" \
-r cli,junit --reporter-junit-export results/otp-real-sms.xml \
--timeout-request 15000 --timeout-script 180000
- uses: actions/upload-artifact@v7
if: always()
with:
name: otp-real-sms-junit
path: results/otp-real-sms.xml
- name: Apaga o arquivo do environment
if: always()
run: rm -f ci.postman_environment.json # faz diferença em runners self-hosted
- A chave vai para o arquivo num passo separado, fora da linha de comando, como pede o guia de secrets do GitHub; o resto entra por
env:e--env-var. - Defina
OTP_MAX_PRICEcomo variável do repositório, para uma alta de preço não encarecer cada execução sem ninguém perceber. - Suba só o JUnit como artefato: o reporter JSON do Newman pode gravar os valores do environment, secrets incluídos.
- Workflow agendado roda no branch padrão, em UTC, pode atrasar e é desativado após 60 dias sem atividade em repositório público. Sem gatilho de pull request, nenhum PR gasta o seu saldo.
Custo e limites
- Cada execução compra um número. O preço depende do serviço e do país, e o
otp_max_pricepõe um teto. Agendado em dias úteis, dá uns 22 números por mês. - Se nenhum SMS chega, o Cancel devolve o valor. Se o SMS chega, o número é cobrado, mesmo que o seu app recuse o código depois.
- A ativação dura cerca de 20 minutos; os 2 minutos de polling cabem com folga.
- Alguns serviços recusam números virtuais, e este teste não serve para contornar isso em serviços de terceiros. Se é o seu próprio app que recusa, isso já é um achado do teste: decida se o antifraude deve mesmo barrar esses números. Se o seu app só rejeita certos prefixos,
phoneExceptionno corpo da compra exclui esses prefixos.
Uso responsável
- Teste só apps que são seus ou que você tem autorização para testar, de preferência em staging. Não use números alugados para criar contas em massa nem para driblar a verificação de outros serviços: isso costuma violar os termos desses serviços e não é o que este teste mede.
- O número é seu só durante a ativação: não o vincule a uma conta que você vá precisar recuperar.
- LGPD: só dados fictícios nas contas de teste. Telefone e texto de SMS podem identificar alguém, então guarde o mínimo e apague junto com as contas de teste.
Resumindo
Mock e número de teste em todo PR, mais uma execução agendada no Newman com número real. Ela pega o que o mock não pega: SMS que nunca chega, template quebrado, país onde o seu provedor de SMS não entrega.
Os endpoints acima são da API da HeroSMS; os códigos de erro e o schema completo estão na referência da API.
E aí, na collection de vocês o passo do OTP já é automático, ou ainda tem alguém colando o código do celular no {{otp_code}}?