TL;DR
Executar testes do ReadyAPI no Jenkins é possível através da ferramenta de linha de comando testrunner e do plugin SmartBear Jenkins, mas exige que o ReadyAPI esteja instalado nos agentes de build e envolve frequentes dores de cabeça de configuração. A integração CI/CD do Apidog funciona através de um CLI simples instalado via npm, sem requisitos de software de agente e sem licenciamento por execução.
Introdução
Integrar testes de API a um pipeline CI/CD é uma das coisas mais valiosas que uma equipe de testes pode fazer. Capturar regressões em cada pull request, antes que o código chegue ao ambiente de staging ou produção, vale o esforço de configuração.
O ReadyAPI oferece suporte à integração com Jenkins através de dois mecanismos: a ferramenta de linha de comando testrunner e o plugin oficial SmartBear Jenkins. Ambos funcionam, mas cada um vem com sua complexidade. Este guia aborda como configurar o ReadyAPI com Jenkins, os problemas comuns que você encontrará e como o Apidog oferece a mesma integração de pipeline com menos sobrecarga de infraestrutura.
Configurando o ReadyAPI no Jenkins: a abordagem testrunner
O testrunner é o motor de execução de linha de comando do ReadyAPI. Quando o Jenkins precisa executar testes do ReadyAPI de forma headless, ele chama o testrunner com argumentos apontando para um arquivo de projeto.
Pré-requisitos:
O ReadyAPI deve ser instalado em cada agente Jenkins que executa testes de API. Este é o maior requisito operacional. Se você tem cinco agentes de build e testes do ReadyAPI são executados em qualquer um deles, todos os cinco precisam ter o ReadyAPI instalado. Isso cria:
- Uma carga de manutenção de instalação quando o ReadyAPI é atualizado.
- Uma questão de licenciamento: cada instalação de agente requer sua própria licença? A política de licenciamento CI/CD da SmartBear varia por contrato. Confirme com sua equipe de contas.
- Aumento do tamanho da imagem do agente e do tempo de inicialização para agentes baseados em nuvem.
Comando básico do testrunner:
No Linux/macOS:
/path/to/ReadyAPI/testrunner.sh \
-r \
-f /path/to/results \
-s "TestSuiteName" \
-c "TestCaseName" \
/path/to/project.xml
No Windows:
C:\ReadyAPI\testrunner.bat ^
-r ^
-f C:\results ^
-s "TestSuiteName" ^
-c "TestCaseName" ^
C:\projects\project.xml
Principais flags do testrunner:
-r: gera relatório XML compatível com JUnit-f <diretório>: diretório de saída para os resultados-s <nome>: executa um conjunto de testes específico (omita para executar todos)-c <nome>: executa um caso de teste específico (omita para executar todos)-e <ambiente>: especifica o ambiente a ser usado-P <nome>=<valor>: sobrescreve propriedades do projeto
Etapa do pipeline Jenkins:
Em um Jenkinsfile:
stage('API Tests') {
steps {
sh '''
/opt/readyapi/testrunner.sh \
-r \
-f ${WORKSPACE}/test-results \
-e ${ENVIRONMENT} \
${WORKSPACE}/project.xml
'''
junit 'test-results/*.xml'
}
}
A etapa junit publica os resultados no Jenkins para que as falhas apareçam no relatório de build.
Usando o plugin SmartBear Jenkins
A SmartBear mantém um plugin Jenkins para ReadyAPI disponível no diretório de plugins do Jenkins. O plugin fornece uma etapa de build na UI do Jenkins em vez de exigir que você escreva comandos de shell manualmente.
Para instalá-lo:
- Vá para Jenkins > Gerenciar Jenkins > Gerenciador de Plugins.
- Procure por “SmartBear ReadyAPI Functional Testing”.
- Instale e reinicie o Jenkins.
Após a instalação, você configura o caminho de instalação do ReadyAPI nas configurações globais do Jenkins e, em seguida, adiciona uma etapa de teste do ReadyAPI ao seu job de build, selecionando-a na lista suspensa de etapas de build.
O plugin lida com a construção de argumentos para você e integra os resultados aos relatórios de teste do Jenkins. Para equipes que preferem a configuração via GUI em vez de scripts de pipeline Groovy, o plugin reduz o tempo de configuração.
Limitações do plugin: O plugin está vinculado a versões específicas do Jenkins e do ReadyAPI. As atualizações do plugin ficam atrasadas em relação às versões do ReadyAPI e do Jenkins. Equipes que utilizam o ReadyAPI mais recente podem encontrar problemas de compatibilidade que exigem a espera por uma atualização do plugin.
Problemas comuns com Jenkins + ReadyAPI
Testrunner trava na inicialização. O ReadyAPI é um aplicativo Java/Swing. Quando iniciado de forma headless no CI, ele às vezes tenta inicializar componentes da GUI. Defina a variável de ambiente DISPLAY ou use os argumentos JVM -Djava.awt.headless=true se você encontrar isso.
Falhas de validação de licença. O ReadyAPI valida sua licença na inicialização. Se o agente CI não conseguir alcançar o servidor de licenças da SmartBear (comum em redes corporativas restritas), os testes falharão com um erro de licença em vez de uma falha de teste. Você precisa configurar as configurações do servidor de licença flutuante ou o licenciamento offline.
Erros de falta de memória. As configurações padrão de heap da JVM no testrunner são conservadoras. Grandes conjuntos de testes ou projetos com muitos arquivos de dados podem precisar que as configurações -Xmx sejam ajustadas. Edite o arquivo testrunner.sh ou testrunner.bat para aumentar o heap:
-Xms128m -Xmx1024m
Problemas de caminho com arquivos de projeto. Os projetos do ReadyAPI referenciam arquivos externos (fontes de dados, esquemas, scripts) usando caminhos. Ao executar no CI, os caminhos relativos funcionam apenas se o diretório de trabalho estiver definido corretamente. Caminhos absolutos em arquivos de projeto causam problemas quando o projeto é movido entre máquinas. Use as propriedades do projeto para os caminhos e defina-os via flags -P em tempo de execução.
Testes passam localmente, mas falham no CI. Frequentemente causado por diferenças de ambiente: dados diferentes em arquivos externos, valores diferentes de variáveis de ambiente ou caminhos hardcoded. Use o recurso Ambiente do ReadyAPI com seleção explícita de ambiente no argumento -e do testrunner.
Integração do Apidog com Jenkins: uma abordagem mais simples
O CLI runner do Apidog é instalado via npm e não requer um aplicativo desktop no agente de build.
Instalação no agente Jenkins:
npm install -g apidog-cli
Ou em uma etapa de pipeline:
npm ci
# apidog-cli is in devDependencies
Executando testes em um Jenkinsfile:
stage('API Tests') {
steps {
sh '''
apidog run \
--collection ${WORKSPACE}/apidog-collection.json \
--environment staging \
--reporter junit \
--reporter-junit-export ${WORKSPACE}/results/report.xml
'''
junit 'results/report.xml'
}
}
Principais diferenças em relação ao ReadyAPI:
Nenhum aplicativo desktop nos agentes. O CLI do Apidog é um pacote Node.js leve. Instale-o em segundos, não em minutos. Sem problemas de inicialização de GUI, sem requisitos de conectividade com o servidor de licenças.
Sem preocupações com licenciamento por execução. O Apidog não cobra por execução de CI. Execute quantos ciclos de teste por dia seu pipeline exigir.
Configuração de ambiente via variáveis de ambiente ou flags. Passe credenciais e URLs base como variáveis de ambiente diretamente do repositório de credenciais do Jenkins:
withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
sh 'apidog run collection.json -e production --env-var "apiKey=${API_KEY}"'
}
Comparação com GitHub Actions:
Para equipes que também usam GitHub Actions, a abordagem do Apidog é igualmente limpa:
- name: Run API tests
run: |
npm install -g apidog-cli
apidog run collection.json --environment staging
env:
API_BASE_URL: ${{ vars.STAGING_URL }}
API_KEY: ${{ secrets.API_KEY }}
O equivalente do ReadyAPI exige um runner auto-hospedado com o ReadyAPI instalado ou uma construção complexa de imagem Docker. Nenhum dos dois é tão direto.
Migrando CI/CD do ReadyAPI para o Apidog
Se você está migrando sua suíte de testes e precisa atualizar sua configuração CI/CD simultaneamente:
- Exporte suas definições de API do ReadyAPI e importe-as para o Apidog.
- Instale o CLI do Apidog em seus agentes Jenkins.
- Adicione uma etapa de teste do Apidog ao seu pipeline, juntamente com a etapa existente do ReadyAPI.
- Execute ambos em paralelo. Compare as taxas de falha e a cobertura de teste.
- Remova a etapa do ReadyAPI assim que tiver confiança na cobertura do Apidog.
- Remova o ReadyAPI dos agentes de build durante a próxima atualização da imagem do agente.
FAQ
O testrunner do ReadyAPI requer uma licença de CI separada?A política de licenciamento da SmartBear para uso em CI/CD varia por contrato. Alguns acordos incluem direitos de execução em CI/CD na licença padrão; outros exigem um acordo separado. Verifique seu contrato ou entre em contato com seu gerente de contas da SmartBear antes de presumir que as execuções em CI estão cobertas.
Os testes do ReadyAPI podem ser executados em contêineres Docker?Sim, com esforço. Você pode construir uma imagem Docker com o ReadyAPI instalado e usá-la como um contêiner de agente Jenkins. A imagem é grande (o ReadyAPI é um aplicativo desktop) e requer configuração headless. Funciona, mas adiciona complexidade em comparação com ferramentas criadas para ambientes CI conteinerizados.
O Apidog suporta execução paralela de testes no Jenkins?Sim. Você pode executar várias instâncias do CLI do Apidog em estágios paralelos do Jenkins, cada uma executando uma coleção ou ambiente diferente. A execução paralela é controlada através do seu Jenkinsfile, não pelo CLI do Apidog.
Qual formato de relatório de teste o Apidog produz para o Jenkins?O CLI do Apidog pode produzir relatórios JUnit XML, que o Jenkins analisa e exibe nativamente na seção de resultados de teste. O formato é o mesmo que o testrunner do ReadyAPI produz.
Os scripts de teste do Apidog são executados no mesmo processo que o CLI runner?Sim. Os scripts de teste JavaScript são executados dentro do processo Node.js do CLI do Apidog. Não há um ambiente de execução de scripts separado para configurar.
Existe um plugin oficial do Apidog para Jenkins?O CLI do Apidog é executado como uma etapa de shell no Jenkins, o que não requer um plugin dedicado. Essa abordagem é mais simples de manter do que integrações baseadas em plugins que precisam de atualização quando o Jenkins ou o Apidog lançam novas versões.
A integração do ReadyAPI com o Jenkins funciona, mas exige um gerenciamento de infraestrutura significativo. Para equipes que desejam simplificar sua configuração CI/CD, mantendo uma cobertura abrangente de testes de API, a abordagem CLI do Apidog elimina os pontos problemáticos mais comuns: requisitos de software de agente, dependências de servidor de licenças e configuração complexa de ambiente.