0

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.setNextRequest chegou 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ávelExemploObservaçã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_pricevazioTeto opcional de preço por número
app_urlhttps://staging.example.comO 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.

#NomeRequestCorpo
1Buy numberPOST https://hero-sms.com/api/v1/activations{{buy_body}}
2Send code (app)POST {{app_url}}/api/otp/send{"phone": "{{phone}}"}
3Poll OTPGET https://hero-sms.com/api/v1/activations/{{activation_id}}/otp/lastnenhum
4Verify code (app)POST {{app_url}}/api/otp/verify{"phone": "{{phone}}", "code": "{{otp_code}}"}
5Finish numberPOST https://hero-sms.com/api/v1/activations/{{activation_id}}/finishnenhum
6Cancel numberDELETE 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 data vazio contam como "ainda não", a menos que o title diga que a ativação foi encerrada. Um 404 por ID errado vai parecer timeout.
  • O Retry-After no 429 só está documentado no endpoint de ofertas, daí o fallback de 5 segundos.
  • O setNextRequest nã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, com info.minActivationTime; cerca de 2 minutos nos exemplos da referência). O script espera e tenta de novo.
  • Com SMS atrasado, a API responde OTP_RECEIVED e o script encerra pelo Finish, sem reembolso.
  • Se o runner morrer, número sem SMS é reembolsado no saldo, e GET /activations lista 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-script precisa ser maior que o setTimeout mais longo, aqui a espera do cancelamento.
  • Nada de --bail nem de --timeout curto, que podem pular o Finish e o Cancel. Nada de -n acima 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_PRICE como 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_price põ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, phoneException no 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}}?

Carregando publicação patrocinada...