Como Executar Testes de API Apidog CLI no Harness CI/CD

Você executa testes do Apidog CLI no Harness adicionando um estágio de CI com uma etapa Run: instale o apidog-cli, execute apidog run e publique o XML JUnit gerado. Guarde o token do Apidog como segredo do Harness, referencie-o com <+secrets.getValue("...")> e configure reports: JUnit apontando para apidog-reports/*.xml.

Experimente o Apidog hoje

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 gerenciada ou auto-hospedada, e pode entregar artefatos ao Harness CD para implantação.

No Harness, você define pipelines em YAML:

• pipeline contém metadados e stages.
• Cada stage pode ser do tipo CI.
• O spec do estágio define a infraestrutura de build.
• execution contém as etapas.
• Uma etapa Run executa comandos de shell.

Para testes de API, o fluxo é direto: o pipeline executa o Apidog CLI, o CLI retorna sucesso ou falha, e o Harness decide se o pipeline continua. Como o Apidog CLI pode gerar JUnit XML, o Harness também exibe os resultados na aba nativa de testes.

Como o Harness CI funciona

A estrutura básica de um pipeline de CI no Harness é:

pipeline:
  stages:
    - stage:
        type: CI
        spec:
          execution:
            steps:
              - step:
                  type: Run
                  spec:
                    shell: Sh
                    command: |-
                      echo "executar testes aqui"

Para comandos de shell, use uma etapa Run. O campo command aceita comandos multilinha com |-.

Exemplo mínimo:

- step:
    type: Run
    name: Run Apidog CLI Tests
    identifier: run_apidog_cli_tests
    spec:
      shell: Sh
      command: |-
        npm install -g apidog-cli
        apidog run --help

A partir daí, você adiciona autenticação, IDs do cenário/ambiente e publicação de relatórios JUnit.

O Apidog CLI em um minuto

O Apidog CLI executa pela linha de comando os cenários de teste criados visualmente no Apidog. Você modela e depura os testes na interface do Apidog e executa a mesma suíte em modo headless no CI, de forma semelhante ao Newman para coleções do Postman. Para comparação, veja Apidog CLI vs Newman.

Instalação e execução básica:

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

Flags importantes para CI:

Flag	Função
--access-token	Autentica a execução no Apidog
-t	Define o ID do cenário de teste
-e	Define o ID do ambiente
-r	Define os reporters, como cli, html, json, junit
--out-dir	Define onde salvar os relatórios
-n	Define a quantidade de iterações

Use -r cli,junit para que o Harness consiga ler o XML gerado. Para detalhes sobre os arquivos produzidos, consulte Apidog CLI test reports.

Armazenando o token de acesso do Apidog como segredo do Harness

Não coloque o token diretamente no YAML.

No Harness:

1. Acesse as configurações do projeto, organização ou conta.
2. Abra Secrets.
3. Crie um novo segredo do tipo Text.
4. Use o identificador apidog_token.

Depois, referencie o segredo no YAML:

<+secrets.getValue("apidog_token")>

Para segredos em outros escopos:

<+secrets.getValue("org.apidog_token")>
<+secrets.getValue("account.apidog_token")>

Em comandos de shell, envolva a expressão em aspas simples:

--access-token '<+secrets.getValue("apidog_token")>'

Isso evita problemas caso o token contenha caracteres como $. Veja também as notas de autenticação do Apidog CLI.

Pipeline Harness Cloud

Use Harness Cloud quando seus endpoints de teste forem acessíveis publicamente e você não precisar manter infraestrutura própria.

No Harness Cloud:

• Use platform e runtime.
• Não defina image na etapa Run.
• O ambiente gerenciado já inclui Node.js e npm.
• Use cloneCodebase: false se os testes estiverem no Apidog e o pipeline não precisar do repositório.

Pipeline completo:

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:

• YOUR_PROJECT pelo identificador do projeto no Harness.
• YOUR_ORG pelo identificador da organização.
• 605067 pelo ID do cenário de teste no Apidog.
• 1629989 pelo ID do ambiente no Apidog.

Publicando resultados de teste no Harness

O bloco responsável pela publicação dos resultados é este:

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml

O Harness lê arquivos JUnit XML e mostra os resultados na aba de testes do build. O Apidog CLI gera esses arquivos quando você usa:

-r junit

ou:

-r cli,junit

Se você remover junit da lista de reporters, a etapa ainda pode passar, mas o Harness não terá XML para exibir na interface.

O Harness também possui Test Intelligence com etapa Test, mas esse recurso é voltado a testes de unidade em nível de linguagem. Para cenários de API executados pelo Apidog CLI, use uma etapa Run com reports: JUnit.

Alternativa com delegado auto-hospedado

Use um delegado auto-hospedado quando precisar de:

• Acesso a endpoints privados.
• Execução dentro da sua rede.
• Runtime customizado.
• Controle sobre o cluster ou VMs.
• Evitar créditos de build do Harness Cloud.

Com infraestrutura Kubernetes via delegado:

• O estágio usa infrastructure, não platform/runtime.
• Cada etapa Run precisa de connectorRef e image.
• A etapa executa dentro de um contêiner.

Exemplo:

        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 imagem node:20 fornece Node.js e npm dentro do pod. Os valores de connectorRef devem apontar para conectores Kubernetes e Docker configurados no Harness.

Não misture os dois modelos no mesmo estágio:

• Harness Cloud usa platform + runtime.
• Delegado auto-hospedado usa infrastructure.

Escolhendo entre Harness Cloud e delegado

Escolha com base no alcance de rede e no controle necessário sobre a infraestrutura.

Fator	Harness Cloud	Delegado auto-hospedado
Configuração	Sem infraestrutura própria, npm pré-instalado	Você gerencia cluster ou VMs
Alcance de rede	Endpoints públicos	Endpoints privados e internos
Etapa Run precisa de imagem	Não	Sim, em Kubernetes
Modelo de custo	Usa créditos de build	Usa sua própria computação
Melhor para	APIs na nuvem, início rápido	APIs internas, runtimes customizados

Comece com Harness Cloud se o ambiente do Apidog acessar endpoints públicos. Migre para um delegado quando os testes precisarem rodar dentro da sua rede privada. O comando apidog run permanece praticamente igual.

Execuções orientadas a dados

Para testes parametrizados, passe um arquivo CSV ou JSON com -d ou --iteration-data.

Exemplo:

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 usando os dados do arquivo.

Em um pipeline Harness, você precisa preparar o arquivo antes da execução. Por exemplo, se o arquivo estiver no repositório:

spec:
  cloneCodebase: true
  execution:
    steps:
      - step:
          type: Run
          name: Run data-driven Apidog tests
          identifier: run_data_driven_apidog_tests
          spec:
            shell: Sh
            command: |-
              npm install -g apidog-cli

              apidog run \
                --access-token '<+secrets.getValue("apidog_token")>' \
                -t 605067 \
                -e 1629989 \
                -d ./data.csv \
                -n 5 \
                -r cli,junit \
                --out-dir ./apidog-reports
            reports:
              type: JUnit
              spec:
                paths:
                  - apidog-reports/*.xml

Para o padrão completo, veja Apidog CLI data-driven testing e o guia de automação de testes de API.

Por que projetar testes no Apidog primeiro

O CLI executa cenários que já existem no projeto Apidog. O fluxo recomendado é:

1. Criar ou importar sua API no Apidog.
2. Montar cenários de teste visualmente.
3. Configurar ambiente e variáveis.
4. Validar localmente no Apidog.
5. Executar o mesmo cenário no Harness com apidog run.

Apidog é uma plataforma API all-in-one para design, depuração, teste, mocking e documentação.

Você pode encadear requisições, extrair valores de uma resposta para a próxima e adicionar asserções pela interface. Depois, o CLI executa a mesma suíte em modo headless no CI.

Como o Apidog é nativo de OpenAPI e oferece suporte a branches e workspaces de equipe, desenvolvedores backend e QA podem trabalhar sobre a mesma fonte de verdade. O cenário validado na interface é o mesmo cenário executado pelo comando apidog run.

Para outros padrões de pipeline, veja:

• O que é CI/CD
• Guia de workflow com GitHub Actions
• Como integrar testes Apidog com Jenkins

Baixe o Apidog gratuitamente para construir seu primeiro cenário de teste e conectá-lo ao Harness com o YAML acima.

Perguntas Frequentes

O que é Harness CI/CD?

Harness CI/CD é uma plataforma para construir, testar e implantar software com pipelines definidos em YAML. Um estágio de CI roda builds e testes; um estágio de CD lida com implantação.

Como o Harness CI funciona?

Um pipeline contém estágios. Um estágio de CI declara infraestrutura de build e uma lista de etapas. Uma etapa Run executa comandos de shell, como instalar o Apidog CLI e executar apidog run.

Como armazenar e usar segredos no Harness?

Crie um segredo de texto no gerenciador de segredos do Harness e referencie-o com:

<+secrets.getValue("identificador")>

Use org. ou account. para segredos nesses escopos. Em comandos de shell, envolva a expressão em aspas simples.

Como publicar resultados de teste no Harness?

Adicione reports à etapa Run:

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml

O Apidog CLI gera o XML quando você passa -r junit ou -r cli,junit.

O Harness CI é gratuito?

O Harness oferece plano gratuito para CI, e builds no Harness Cloud consomem créditos incluídos no plano. Verifique a página de preços atual do Harness para limites e valores atualizados.

Posso executar testes do Apidog CLI sem clonar meu repositório?

Sim. Use:

cloneCodebase: false

Se os cenários estiverem no Apidog, o CLI usa o token de acesso e os IDs do cenário e ambiente para executar os testes sem precisar do código-fonte.