Teste sintético: como criar um teste de API em etapas e uma jornada no navegador usando KeepWatch

Autor: Pedro Tebaldi PM do KeepGreen

Publicado out/2026

CPU, memória e disco aparecem em verde no painel enquanto o cliente não consegue fechar o pedido. Nenhuma métrica interna está errada nessa hora: ela só não mede a jornada. O teste sintético de monitoração cobre essa lacuna: refaz a jornada pelo lado de fora, num intervalo fixo, conferindo a resposta de cada passo.

Este tutorial monta dois testes no KeepWatch, a plataforma de observabilidade de aplicações da OpServices. Um deles é uma compra pela API em cinco etapas; o outro, uma jornada de cinco passos num navegador de verdade. Depois, mostra como ler o resultado da falha e como chegar ao serviço do backend que quebrou.

Todas as telas vêm de um lab interno do KeepWatch. Loja, Banco e Frota são aplicações de demonstração deste laboratório. Já o teste de navegador mede a página real do produto no site da OpServices.

O que um teste sintético confere e o que fica de fora

Um teste sintético é uma requisição ou jornada de navegador que a ferramenta executa em intervalo fixo, de um ou mais locais. A cada execução, ele confere o status, o conteúdo e o tempo de cada passo. O resultado diz se o serviço funciona agora para quem chega de fora, mesmo quando nenhum usuário real está acessando.

No KeepWatch, o filtro da lista de Sintéticos separa três tipos. Disponibilidade faz uma requisição só e avisa quando o certificado ou o domínio está perto de vencer. API em etapas encadeia várias requisições, de modo que o que uma devolve alimenta a próxima. Navegador abre a página num Chromium, clica, digita e confere o que aparece na tela.

Quem procura a definição longa, com o papel do teste nos SLOs e no pipeline de entrega, encontra no guia de monitoração sintética. Aqui o foco é a montagem e a leitura do resultado.

Esse robô só percorre o caminho que alguém roteirizou, então não enxerga a rede móvel ruim do cliente nem o fluxo que ninguém previu. Esse território é do monitoramento de usuário real; a comparação entre sintético e RUM mostra onde cada abordagem entra.

Assim que a lista de Sintéticos abre, os indicadores do topo mostram quantos testes estão falhando, instáveis ou com certificado perto de vencer:

Passo 1: escolha a jornada e a conta que o robô vai usar

Comece pela jornada que custa dinheiro quando quebra: login, busca, carrinho, pagamento, emissão de boleto. Vale o critério do mapeamento de jornadas críticas do usuário: um teste por jornada crítica rende mais que dez testes de página institucional.

Depois, decida com que conta o teste entra, já que ele roda em produção e tudo o que cria fica gravado. Quando uma etapa grava alguma coisa, o construtor do KeepWatch calcula quantas gravações isso dá por dia e oferece uma etapa de limpeza.

No teste da Loja, que roda a cada 5 minutos, são 288 pedidos por dia. A orientação da própria interface é direta: use um endpoint ou uma conta de teste e apague o que ela cria.

Senha, chave de API e token fixo ficam no cofre do KeepWatch e entram na etapa como {{cofre.nome}}. A tela também desaconselha credencial em parâmetro da URL, porque o endereço viaja inteiro para o log do proxy e do servidor.

Passo 2: monte os passos do teste

A montagem muda conforme o tipo: na API você descreve cada requisição, enquanto no navegador você grava a jornada clicando no próprio site.

API em etapas: requisição, conferência e variável

Cada etapa tem método, URL, cabeçalhos, as conferências que decidem se ela passou e os valores extraídos da resposta. O exemplo é o teste Loja · compra pela API, que entra, lista produtos, cria um pedido, confere esse pedido e o cancela no fim.

Encadear é o que separa este teste de um ping na URL. Uma etapa de login costuma devolver um token, enquanto a de criação devolve o identificador do pedido. No teste da Loja, esse identificador vira a variável {{pedido}} e entra na URL das duas etapas seguintes.

Segundo o próprio construtor, o caminho mais curto é rodar Testar até aqui na etapa e clicar no valor que aparece na resposta. Esse clique cria a regra de conferência ou a variável, que só existe durante a execução do teste.

Conferências cobrem status, campo do JSON e texto da resposta, com operadores como =, ≠, contém, casa (regex) e existe. Status 200 sozinho prova pouco, porque uma API pode devolver 200 com a lista de itens vazia enquanto a vitrine aparece sem produto.

Na última etapa, marcada com ↺, fica a limpeza: um DELETE /pedidos/{{pedido}} que desfaz o que o teste criou. O construtor exige que ela fique no fim e recusa um teste que só tenha limpeza. Vale ainda separar o teste de API em produção do teste de API no deploy, tema do guia de monitoramento de APIs.

Na aba Etapas do teste da Loja, cada linha é uma requisição, com a conferência que mais falhou nas últimas 24 horas:

Jornada no navegador: gravar navegando ou importar do Chrome

Para criar o teste de navegador há dois caminhos, dos quais só um pede uma gravação feita antes. Gravar navegando abre o site num navegador do servidor do KeepWatch, o mesmo de onde o teste vai rodar e com a mesma rede.

Cada clique, digitação e escolha vira um passo, sem nada para instalar na máquina de quem grava. Durante a gravação, a senha digitada vira segredo do teste na hora. Campo preenchido com segredo do cofre sai coberto na captura de tela de cada execução, o que evita vazar credencial no histórico.

Quem já gravou a jornada no Recorder do Chrome ou do Edge pode importar o arquivo. O Recorder exporta a gravação em JSON, conforme a referência do painel Recorder do DevTools; a importação do KeepWatch converte esse arquivo em passos.

Reduzido aos campos que importam para o teste, o formato da gravação é este:

{
  "title": "Site KeepWatch: conferir conteúdo",
  "steps": [
    { "type": "setViewport", "width": 1920, "height": 1080,
      "deviceScaleFactor": 1, "isMobile": false, "hasTouch": false, "isLandscape": false },
    { "type": "navigate", "url": "https://www.opservices.com.br/keepwatch/" },
    { "type": "click", "target": "main",
      "selectors": [["aria/Testes de fora"], ["text/Testes de fora"]],
      "offsetX": 40, "offsetY": 11 },
    { "type": "waitForElement",
      "selectors": [["text/Monitoração sintética"]] }
  ]
}

Repare nos seletores: aria/Testes de fora aponta o link pelo nome acessível, que sobrevive a uma troca de CSS ou de layout.

No KeepWatch, a busca pelo elemento usa papel acessível, rótulo, test-id, CSS, texto ou XPath. Quando só consegue achá-lo por posição ou por classe gerada no build, a ferramenta marca o passo como frágil. Esse tipo de seletor tende a quebrar no próximo deploy do site.

Além de clicar e digitar, um passo pode passar o mouse, selecionar opção de lista, pressionar tecla ou esperar alguns segundos. Também pode conferir um texto ou um pedaço da URL e extrair um valor da página.

Na jornada do laboratório, por exemplo, o robô abre a página, confere o título e clica em Testes de fora. Em seguida confere a seção de monitoração e clica em Agendar uma Demo.

A aba Passos mostra a jornada gravada, a captura que o robô tirou na falha e a rede e o console registrados:

Passo 3: diga ao teste o que conta como falha

Uma execução que falha não deveria acordar ninguém, porque rede oscila e um destino lento num minuto responde normal no seguinte. O alerta que dispara a cada soluço treina o plantão a ignorar o próximo. Por isso o KeepWatch separa três estados e deixa cada teste definir a fronteira entre eles.

O segundo controle é o local de execução: além do servidor do KeepWatch, o mesmo executor pode rodar em outra rede. Ele sobe com um docker run e mede o que só se alcança de dentro da empresa ou da rede de onde o cliente acessa.

No teste do site, o servidor local teve 2 falhas em 49 execuções nas últimas 24 horas. O executor nos Estados Unidos não teve nenhuma em 46. Como a regra exige os dois locais falhando juntos, o teste ficou instável e não falhando: o problema estava num ponto só.

Na aba Por local, o mesmo teste aparece instável no servidor do KeepWatch enquanto o executor dos Estados Unidos segue saudável:

Quando implantamos o OpMon na Klabin, que tem mais de 700 dispositivos monitorados, colocamos robôs que simulam o acesso de usuários reais. Eles passaram a acusar o problema antes do impacto na operação. No mesmo projeto, a notificação passou a sair só para incidente real, como descreve o case da Klabin.

O intervalo fecha a conta: o laboratório usa 1 minuto para disponibilidade de endpoint e 5 minutos para fluxo de API. Jornada de navegador roda a cada 30 minutos, porque pesa mais no destino e no executor. São escolhas do laboratório, não regra do produto: o intervalo certo é o menor que o destino aguenta sem distorcer o próprio tráfego.

Passo 4: ligue o alerta ao teste, não ao gráfico

No detalhe de cada teste, o botão Criar uma regra de alerta para este teste abre regras prontas. Há regra para quando o teste falhar, ficar lento, tiver uma etapa lenta ou estiver com certificado ou domínio vencendo.

Nos testes de navegador entram ainda LCP, CLS e TTFB: página que demora a aparecer, layout que pula e servidor lento. Cada regra chega com o limiar preenchido. A de LCP, por exemplo, nasce com aviso em 2,5 s sustentado por 15 minutos, de modo que um carregamento lento isolado não dispara nada.

O aviso sai por e-mail, Microsoft Teams, Slack, Telegram, webhook ou no formato do Alertmanager, aceito por muitas ferramentas de eventos e de plantão. A regra avisa duas vezes, quando o problema começa e quando passa. Certificado e domínio têm aviso próprio a 30 e a 7 dias do vencimento.

Como ler um teste que já está rodando

Quando o teste falha, o plantão quer saber qual etapa quebrou, desde quando e se o problema é da aplicação ou do caminho. O detalhe do teste responde as três perguntas na primeira tela.

Cascata, última falha e etapa que mais falha

Na cascata aparece o tempo de cada etapa da última execução. No teste da Loja, a criação do pedido levou 433 dos 576 milissegundos da compra inteira. É nessa etapa que um aumento de latência tende a aparecer primeiro.

Ao lado, o cartão de última falha traz a mensagem que o teste registrou: etapa 2 · Listar produtos: status 500 (esperado == 200). A aba Etapas soma 24 horas e mostra qual etapa concentra as falhas, com o motivo mais comum de cada uma. Etapa que não rodou porque uma anterior falhou não entra na conta dela.

Na visão geral do teste da Loja, a cascata da última execução e o cartão de última falha ficam lado a lado:

Web Vitals medidos pelo robô

No teste de navegador, cada execução mede LCP, CLS, FCP e TTFB da página inicial. A tela compara os valores com as faixas da documentação dos Web Vitals do Google, avaliadas no percentil 75. Nessa régua, LCP é bom até 2,5 s e CLS é bom até 0,1.

Na página do KeepWatch, o p75 de 24 horas ficou em 1.880 ms de LCP e 708 ms de TTFB, os dois na faixa boa. Já o FCP de 1.880 ms caiu na faixa que precisa melhorar.

A própria tela avisa o limite dessa medida: com a máquina ocupada, o navegador do servidor mede mais alto do que o usuário sente. Número de laboratório serve para comparar uma execução com a anterior. Para a experiência real vale a medição de campo, explicada no guia de Core Web Vitals.

Da etapa que falhou ao serviço que quebrou

O teste diz que a listagem de produtos devolveu 500, mas não diz por quê. Quem diz é o trace da aplicação, quando ela manda um.

Se a aplicação também envia traces ao KeepWatch, a falha do teste já chega com o serviço do backend que quebrou. Na falha das 15:58 de 14/10, quem falhou foi o loja-catalogo, num SELECT produto. O erro registrado, OperationalError: no such column: preco_promocional, mostra que o código consulta uma coluna que o banco não tem.

O botão Abrir o trace da falha abre o trace da execução ao lado do próprio teste. Nele aparecem as etapas do robô no serviço keepwatch-synthetic e os spans de loja-web e loja-catalogo até a consulta que devolveu erro.

Em Traces, as execuções do robô carregam atributos synthetic.*, o que permite separar o tráfego sintético do tráfego de usuário.

Quando você clica no botão do cartão de última falha, abre este trace da execução das 15:58:

O que medir na primeira semana

Comece com um teste de disponibilidade por endpoint crítico e um teste de API para a jornada que mais custa quando para. Deixe rodar uma semana antes de ligar alerta para o plantão. Essa semana mostra a taxa de falha normal de cada teste, que é de onde sai o limite de instável.

Depois confira três números, começando pelas falhas que vieram de um local só: isso é ruído de rede e não pede acionamento. Em seguida, veja qual etapa concentra as falhas, que é onde o próximo incidente tende a começar. Por último, meça quanto o teste deixa gravado por dia na base de produção, que precisa ser zero depois da limpeza.

Se a aplicação ainda não manda traces, o teste sintético já entrega disponibilidade, tempo por etapa e vencimento de certificado sem tocar no código. Com traces, a mesma falha passa a chegar com o nome do serviço que quebrou. Para montar essa cobertura nas suas aplicações, fale com um especialista da OpServices.