Como Testar Implantações de Preview do Vercel Automaticamente em 2026

A resposta curta

Você não adiciona um arquivo de workflow, nem escreve um script que extraia a URL de preview dos seus logs de build. O TestSprite se instala como um GitHub App, escuta o evento de implantação que seu pipeline já produz, deduz a URL de preview a partir de um padrão que você define uma única vez, executa seus testes contra ela e publica o resultado de volta como um comentário no pull request.

A configuração leva cerca de dez minutos, exige direitos de administrador para instalar um GitHub App e não requer nenhuma alteração no seu repositório.

Pré-requisito: confirme que o pull request produz uma implantação

O TestSprite é acionado por um evento de implantação, então esse evento precisa existir antes que qualquer outra coisa funcione. Abra qualquer pull request existente e confirme que uma implantação está listada com uma URL clicável, depois abra essa URL e verifique se o ambiente de preview realmente carrega.

No Vercel, isso aparece como um comentário de bot no pull request listando o projeto, um status Ready e um link para o preview. AWS Amplify, Netlify e pipelines auto-hospedados que criam implantações no GitHub produzem todos o mesmo sinal em seu próprio formato — o que importa é que uma implantação exista e sua URL seja acessível.

Passo 1 — conecte o GitHub ao seu workspace

Esta é uma configuração única por workspace. No TestSprite, vá em Workspace Settings → Integrations, encontre a linha GitHub e clique em Connect. Você será redirecionado ao GitHub para escolher a organização ou conta pessoal que possui o repositório, depois escolha All repositories ou Only select repositories e clique em Install & Authorize.

Vale a pena conhecer as permissões solicitadas antes de aprová-las:

O acesso de escrita é usado para publicar os resultados dos testes de volta nos seus pull requests e commits. O TestSprite não envia commits nem modifica seus arquivos de workflow. Se sua organização não aparecer listada durante a instalação, você não tem permissão para instalar GitHub Apps para ela — um proprietário da organização precisa aprová-la.

Passo 2 — conecte o repositório a um projeto

Abra o projeto do TestSprite que você quer conectar, vá na aba GitHub Action e clique em Connect GitHub Action. Depois escolha como os testes devem ser acionados:

Um gatilho já é suficiente para começar. Você pode criar os dois — eles rodam de forma independente um do outro.

Passo 3 — escolha o evento que significa "implantação concluída"

Selecione a aba Pull Request, cole a URL de um pull request existente que tenha uma implantação de preview funcionando e clique em Detect Events. O TestSprite lista os eventos de CI/CD que encontrou nesse pull request — verificações do GitHub Actions, comentários de bot do Vercel ou Amplify, execuções de workflow — e você escolhe qual deles inicia uma execução.

Escolha o evento que dispara depois que a implantação está ativa e a URL é acessível. Esse é o erro de configuração mais comum: um evento que dispara no início do build vai executar seus testes contra uma URL que ainda não está no ar, e todo teste vai falhar.

Passo 4 — preencha o padrão de URL de destino

Cada provedor de hospedagem nomeia URLs de preview de forma diferente, então você informa ao TestSprite como construir a URL para qualquer pull request. Cinco placeholders estão disponíveis:

Compare o padrão com uma URL de preview real, caractere por caractere:

Os nomes de host de preview padrão do Vercel são construídos a partir da branch, por isso {branch-slug} costuma ser o placeholder correto ali em vez de {pr}. Se seu host gera subdomínios aleatórios sem nada previsível neles, configure uma URL de alias estável para o ambiente de preview e use-a no lugar.

Um gatilho de push não precisa de padrão algum — ele roda contra a URL configurada de qualquer ambiente do TestSprite que você selecionar, então escolha Dev para dev ou Production para main.

Passo 5 — envie um evento de teste antes de salvar

Clique em Send Test Event. Isso executa seus testes contra o pull request de exemplo exatamente como um gatilho real faria, para que você possa visualizar todo o fluxo antes de confirmá-lo. Aguarde cerca de 30 segundos e depois volte ao pull request no GitHub — um comentário do TestSprite aparece.

Abra a URL nesse comentário antes de ir adiante. Confirme que ela é acessível e aponta para o ambiente que você espera. Se estiver errada, corrija o padrão e envie outro evento de teste em vez de esperar o próximo pull request para descobrir. Assim que a execução for concluída, o TestSprite atualiza o mesmo comentário com o resultado.

Quando o evento de teste parecer correto, clique em Create Trigger. Ele aparece na lista de Triggers marcado como Active e roda automaticamente em todo pull request futuro. Duas opções alternáveis valem a pena ser definidas deliberadamente:

Se seu preview estiver atrás de Deployment Protection

Este é o modo de falha que parece uma configuração funcionando. Com o Deployment Protection do Vercel ativado, toda URL de preview fica atrás de uma barreira de autenticação, e um testador externo recebe a página de login em vez da sua aplicação. Os testes não geram erro — eles descrevem uma página que ninguém esperava.

A verificação do Passo 5 detecta isso: abra a URL do comentário do TestSprite em uma janela privada. Se você vir uma tela de login do Vercel, a proteção está ativada. As duas formas de seguir em frente são desativar a proteção para o ambiente de preview, ou usar o Protection Bypass for Automation do Vercel, que gera um segredo que o Vercel aceita tanto como parâmetro de query x-vercel-protection-bypass quanto como cabeçalho. Como o padrão de URL de destino é apenas uma URL, a forma de parâmetro de query pode ser anexada a ele:

https://app-git-{branch-slug}-team.vercel.app?x-vercel-protection-bypass=YOUR_SECRET

Gere o segredo em Project Settings → Deployment Protection → Protection Bypass for Automation. Seja criterioso com isso — armazena um segredo de bypass em um campo de configuração, então desativar a proteção nos ambientes de preview é a opção mais limpa quando seus previews não contêm nada sensível.

Lendo o resultado

Quando uma execução termina, o TestSprite atualiza seu comentário no pull request — ou a verificação do commit — com o resultado. O comentário é estruturado, e a última linha é a que mais importa se um agente de IA escreveu o código:

Todo resultado leva de volta ao relatório completo no TestSprite.

Verifique sua configuração

Antes de confiar na integração, confirme os cinco pontos:

1. A integração do GitHub aparece como Connected no seu workspace

2. O repositório aparece dentro da aba GitHub Action do projeto

3. Um gatilho está listado e habilitado

4. Um evento de teste produziu um comentário do TestSprite (pull request) ou uma verificação (push)

5. A URL nesse comentário ou verificação abre o ambiente implantado correto

Solução de problemas

A alternativa via linha de comando

O GitHub App é a resposta certa quando seu pipeline já produz implantações. Se você preferir conduzir a execução a partir do seu próprio workflow — ou não estiver no GitHub — o TestSprite CLI de código aberto faz o mesmo trabalho a partir de qualquer sistema de CI. É gratuito para instalar e licenciado sob Apache-2.0:

npm install -g @testsprite/testsprite-cli
testsprite setup

Aponte um projeto para uma URL que você já resolveu, e execute a suíte até um veredito:

testsprite project update prj_abc123 --url "$PREVIEW_URL"
testsprite test run --all --project prj_abc123 --wait --output json
#   exit 0 = everything passed, exit 1 = something is broken

testsprite ci init github monta um workflow para esse caminho, e o CLI precisa apenas de TESTSPRITE_API_KEY no ambiente, então ele se encaixa no CircleCI, GitLab, Jenkins ou Azure Pipelines com a mesma facilidade. Use --report junit --report-file <path> para um relatório complementar que esses sistemas ingerem nativamente.

Se os fluxos que importam para você estiverem atrás do próprio login da sua aplicação, armazene uma conta de teste no projeto para que as execuções possam autenticar. Ambas as flags são obrigatórias juntas:

testsprite project update prj_abc123 \
  --username qa@example.com \
  --password-file ./.secrets/qa-password

Perguntas frequentes