Você executa testes do Apidog CLI no Harness adicionando um estágio de CI com uma única etapa de execução que instala o apidog-cli, executa o apidog run e publica os resultados do JUnit. Armazene seu token de acesso do Apidog como um segredo do Harness, referencie-o com a expressão <+secrets.getValue("...")> e aponte um bloco de relatório JUnit para a saída XML da CLI. Este guia fornece YAML de pipeline para copiar e colar, tanto para o Harness Cloud quanto para um delegado auto-hospedado.
O que é Harness CI/CD?
Harness CI é o módulo de integração contínua da plataforma Harness. Ele constrói, testa e valida seu código em infraestrutura de construção gerenciada ou auto-hospedada, e então entrega artefatos ao Harness CD para implantação.
Você define tudo como YAML. Um pipeline contém um ou mais estágios. Cada estágio tem um tipo, e um estágio de CI é executado na infraestrutura de construção. Dentro do estágio, um bloco de execução contém uma lista ordenada de etapas que executam seus comandos.
O modelo se alinha perfeitamente com o teste de API. Você adiciona um estágio de CI, insere uma etapa que executa seu comando de teste e permite que o Harness controle a construção com base no resultado. Se os testes falharem, a etapa falha e o pipeline para.
O Harness lê JUnit XML para relatórios de teste. Como o Apidog CLI pode emitir JUnit, você obtém uma aba nativa de Testes com contagem de aprovados e reprovados em cada construção. Nenhum código de integração é necessário.
Como o Harness CI funciona
A hierarquia YAML é rigorosa, então ajuda ver o aninhamento antes de escrever qualquer coisa. Um pipeline de CI se parece com isto de cima para baixo:
pipelinecontém metadados e uma lista destages.- Cada
stagetem umtype: CIe umspec. - O
specdo estágio declara a infraestrutura de construção e um bloco deexecution. executioncontém uma lista desteps.- Cada
steptem umtype,name,identifiere seu própriospec.
Para executar um comando de shell, o tipo de etapa é Run. O spec da etapa Run contém um campo shell (Bash, Sh, PowerShell, Pwsh ou Python) e um campo command que contém seu script. Você escreve comandos multi-linha com o escalar de bloco YAML |-.
Essa única etapa Run é tudo o que você precisa para instalar e executar o Apidog CLI. Tudo o mais neste guia é configuração em torno dessa única etapa.
O Apidog CLI em um minuto
O Apidog CLI é um executor de linha de comando para cenários de teste que você constrói visualmente no Apidog. Você projeta testes no aplicativo e os executa de forma *headless* em qualquer pipeline, similar a como o Newman executa coleções do Postman. Se você quiser uma comparação lado a lado, veja Apidog CLI vs Newman.
Você o instala via npm e executa um único comando:
npm install -g apidog-cli
apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -r cli,junit --out-dir ./apidog-reports
Algumas *flags* importam para o CI. A *flag* --access-token autentica a execução na nuvem e não tem forma abreviada. A *flag* -e define o ambiente e é obrigatória. A *flag* -t seleciona um cenário de teste por ID. A *flag* -r escolhe os *reporters*, e junit é um dos valores suportados (cli, html, json, junit). A *flag* --out-dir controla onde os relatórios são salvos, com o padrão sendo ./apidog-reports.
Essa escolha -r cli,junit é a ponte para o Harness. O CLI escreve JUnit XML no diretório de saída, e o Harness o lê diretamente. Para mais detalhes sobre o que o CLI produz, consulte o guia Apidog CLI test reports.
Armazenando seu token de acesso do Apidog como um segredo do Harness
Nunca codifique o token diretamente no YAML. Primeiro, adicione-o ao gerenciador de segredos do Harness, e depois o referencie.
Na interface do usuário do Harness, vá para as configurações do seu projeto (ou organização/conta), abra Segredos e crie um novo segredo de Texto. Dê a ele o identificador apidog_token. O identificador é o que você referencia no YAML, e ele difere do nome de exibição.
Você referencia o segredo com esta expressão:
<+secrets.getValue("apidog_token")>
Use o identificador dentro das aspas, não o nome de exibição. Para um segredo com escopo de organização, prefixe-o com org. como <+secrets.getValue("org.apidog_token")>. Para um segredo com escopo de conta, use account. em vez disso.
Envolva a expressão em aspas simples dentro de um comando de shell. O token pode conter um caractere $, e as aspas simples impedem que o shell o expanda. Você pode ler mais sobre a configuração do token nas notas de autenticação do Apidog CLI.
Pipeline Harness Cloud (ponto de partida recomendado)
O Harness Cloud oferece máquinas de *build* gerenciadas pelo Harness com Node.js e npm pré-instalados. Não há infraestrutura para manter, e o Linux funciona de forma nativa. Esta é a maneira mais rápida de obter um pipeline funcionando.
No Harness Cloud, o spec do estágio usa um bloco platform e um bloco runtime do type: Cloud. Você não especifica uma image na etapa Run aqui, pois a máquina gerenciada já possui as ferramentas.
pipeline:
name: Apidog API Tests
identifier: apidog_api_tests
projectIdentifier: YOUR_PROJECT
orgIdentifier: YOUR_ORG
stages:
- stage:
name: API Tests
identifier: api_tests
type: CI
spec:
cloneCodebase: false
platform:
os: Linux
arch: Amd64
runtime:
type: Cloud
spec: {}
execution:
steps:
- step:
type: Run
name: Run Apidog CLI Tests
identifier: run_apidog_cli_tests
spec:
shell: Sh
command: |-
npm install -g apidog-cli
apidog run \
--access-token '<+secrets.getValue("apidog_token")>' \
-t 605067 \
-e 1629989 \
-n 1 \
-r cli,junit \
--out-dir ./apidog-reports
reports:
type: JUnit
spec:
paths:
- apidog-reports/*.xml
Substitua 605067 pelo ID do seu cenário de teste e 1629989 pelo ID do seu ambiente. A *flag* -n 1 executa uma iteração. Defina cloneCodebase: false porque os testes estão na nuvem do Apidog, então o pipeline não precisa do seu repositório.
Publicando resultados de teste
O bloco reports na etapa Run é o que exibe os resultados no Harness. Ele aceita um type de JUnit e um spec com uma lista de paths apontando para seus arquivos XML.
reports:
type: JUnit
spec:
paths:
- apidog-reports/*.xml
O Harness analisa apenas JUnit XML para relatórios nativos. Após a compilação, você verá uma aba de Testes com cada cenário, seu status e tempo. O *glob* apidog-reports/*.xml corresponde aos arquivos que o CLI escreveu com -r cli,junit no diretório de saída padrão.
O Harness também oferece Test Intelligence, que usa um tipo de etapa Test separado para executar apenas os testes afetados por uma alteração de código. Essa otimização visa testes de unidade em nível de linguagem, não cenários de API *headless*. Para ingestão de saída do Apidog CLI, a etapa Run simples com um bloco reports do JUnit é o caminho correto.
Se você mudar os *reporters*, mantenha pelo menos junit na lista -r. Sem ele, o CLI não escreve XML, e a aba de Testes permanece vazia mesmo quando a própria etapa é aprovada.
Alternativa de delegado auto-hospedado
Use uma *build* apoiada por delegado quando precisar de acesso à rede privada, um *runtime* personalizado ou legado, ou se quiser evitar os créditos de *build* do Harness Cloud. Um delegado Kubernetes executa cada estágio como um pod.
A estrutura muda de duas maneiras. O spec do estágio usa um bloco infrastructure em vez de platform e runtime. E na infraestrutura Kubernetes, cada etapa Run deve declarar um connectorRef e uma image, porque a etapa é executada dentro de um contêiner que você especifica.
spec:
cloneCodebase: false
infrastructure:
type: KubernetesDirect
spec:
connectorRef: YOUR_K8S_CONNECTOR
namespace: harness-ci
execution:
steps:
- step:
type: Run
name: Run Apidog CLI Tests
identifier: run_apidog_cli_tests
spec:
connectorRef: YOUR_DOCKER_CONNECTOR
image: node:20
shell: Sh
command: |-
npm install -g apidog-cli
apidog run \
--access-token '<+secrets.getValue("apidog_token")>' \
-t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
reports:
type: JUnit
spec:
paths:
- apidog-reports/*.xml
A linha image: node:20 fornece Node.js e npm dentro do *pod*. Os valores de connectorRef apontam para seus conectores Kubernetes e Docker registrados. Não misture os dois estilos de infraestrutura em um único estágio. Um estágio é ou Harness Cloud (platform mais runtime) ou apoiado por delegado (infrastructure), nunca ambos.
Escolhendo entre Harness Cloud e um delegado
Escolha com base em onde suas APIs estão e quem é o proprietário das máquinas de *build*.
| Fator | Harness Cloud | Delegado auto-hospedado |
|---|---|---|
| Configuração | Infraestrutura zero, npm pré-instalado | Você gerencia o cluster ou VMs |
| Alcance da rede | Endpoints públicos | Endpoints privados e internos |
| Etapa Run precisa de imagem | Não | Sim, na infraestrutura Kubernetes |
| Modelo de custo | Usa créditos de build | Sua própria computação |
| Melhor para | APIs na nuvem, início rápido | APIs internas, runtimes personalizados |
Comece com o Harness Cloud se o seu ambiente Apidog atingir *endpoints* públicos. Mude para um delegado quando o seu ambiente de teste estiver atrás de uma VPN ou precisar de um *runtime* que você controla. A etapa Run e o comando Apidog permanecem quase idênticos entre os dois.
Execuções orientadas a dados
Você pode alimentar um arquivo CSV ou JSON na execução para testes parametrizados. A *flag* -d (nome longo --iteration-data) recebe o caminho do arquivo de dados, e -n define a contagem de iterações.
apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -d ./data.csv -n 5 -r cli,junit --out-dir ./apidog-reports
Isso executa o cenário uma vez por linha de dados. Em uma etapa Run do Harness, você faria um git clone ou, de alguma forma, prepararia o arquivo de dados primeiro, e depois apontaria -d para o seu caminho. Para o padrão completo, veja Apidog CLI data-driven testing e o guia mais amplo de automação de testes de API.
Por que projetar testes no Apidog primeiro
O CLI só executa cenários que já existem em seu projeto Apidog. Esse é o ponto. Apidog é uma plataforma API *all-in-one* para design, depuração, teste, *mocking* e documentação, então você constrói seu conjunto de testes uma vez e o reutiliza em todos os lugares.
Você projeta testes com um construtor visual, sem necessidade de *scripting*. Você encadeia requisições, extrai valores de uma resposta para a próxima e adiciona asserções por meio de uma interface de usuário. O CLI então executa essa mesma suíte de forma *headless* no Harness, então o que você depura localmente é o que roda no pipeline.
Como o Apidog é nativo de OpenAPI com suporte a *branchs* e *workspaces* de equipe, seus engenheiros de QA e desenvolvedores *backend* compartilham uma única fonte de verdade. Um cenário aprovado em uma *branch* se torna o mesmo cenário que seu comando apidog run executa. Para padrões de pipeline mais amplos, o guia o que é CI/CD e o guia de *workflow* do GitHub Actions cobrem o mesmo CLI em outros sistemas. O passo a passo do Jenkins em integrar testes Apidog com Jenkins usa o formato de comando idêntico.
Baixe o Apidog gratuitamente para construir seu primeiro cenário de teste e, em seguida, conecte-o ao Harness com o YAML acima.
Perguntas Frequentes
O que é Harness CI/CD?
Harness CI/CD é uma plataforma de pipeline para construir, testar e implantar software. Você define pipelines como YAML, compostos por estágios e etapas. Um estágio de CI é executado em infraestrutura de *build*, seja em máquinas gerenciadas pelo Harness Cloud ou em um delegado auto-hospedado, e um estágio de CD lida com a implantação.
Como o Harness CI funciona?
Um pipeline contém uma lista de estágios. Cada estágio de CI possui uma *spec* que declara a infraestrutura de *build* e um bloco de execução. O bloco de execução executa uma lista ordenada de etapas. Uma etapa Run executa um comando de *shell*, que é onde você instala e executa o Apidog CLI.
Como você armazena e usa segredos no Harness?
Crie um segredo de Texto no gerenciador de segredos do Harness e anote seu identificador. Referencie-o em YAML com <+secrets.getValue("identificador")>, usando o identificador em vez do nome de exibição. Prefixe com org. ou account. para esses escopos, e envolva a expressão em aspas simples dentro de comandos de *shell*.
Como você publica resultados de teste no Harness?
Adicione um bloco reports à sua etapa Run com type: JUnit e uma lista paths apontando para seus arquivos XML. O Harness analisa JUnit XML e mostra os resultados na aba de Testes do *build*. O Apidog CLI emite este XML quando você passa -r junit ou -r cli,junit.
O Harness CI é gratuito?
O Harness oferece um plano gratuito para CI, e as *builds* do Harness Cloud consomem créditos de *build* incluídos no seu plano. Os preços e limites de crédito mudam ao longo do tempo, então verifique a página de preços atual do Harness para valores exatos antes de se comprometer com um nível.
Posso executar testes do Apidog CLI sem clonar meu repositório?
Sim. Defina cloneCodebase: false no estágio quando seus testes estiverem na nuvem do Apidog. O CLI se autentica com seu token de acesso e puxa o cenário e o ambiente por ID, então o pipeline nunca precisa do seu código-fonte para a execução do teste.