Postman CLI: Automação Avançada para Fluxos de Trabalho de API

Construímos APIs todos os dias, e a necessidade de automação, testes e orquestração é primordial. O Postman, uma ferramenta bem conhecida por sua interface amigável, introduziu sua Interface de Linha de Comando (CLI) para suportar automação mais profunda e fluxos de trabalho de CI/CD.

A CLI do Postman não é apenas uma ferramenta para acionar testes; é uma utilidade abrangente que permite que você escreva scripts para interações com APIs, integre-se a pipelines existentes e garanta a integridade das APIs em múltiplos ambientes. Este artigo explora as capacidades avançadas da CLI do Postman, mostrando como ela pode elevar suas práticas de desenvolvimento e teste de APIs.

A Evolução da CLI do Postman

Antes de mergulhar nos detalhes técnicos, é importante entender por que o Postman introduziu sua CLI. A interface gráfica do Postman é perfeita para uso interativo — ideal para explorar, testar e depurar APIs.

No entanto, em um ambiente DevOps moderno, a automação é crucial. Os pipelines de Integração Contínua / Implantação Contínua (CI/CD) requerem testes automatizados e validação de APIs, e é aí que entra a CLI do Postman. Ela preenche a lacuna entre testes manuais de APIs e fluxos de trabalho de APIs totalmente automatizados e integrados. Esta utilidade permite que as equipes executem coleções, testes e integrações diretamente de um terminal, desbloqueando o potencial para processos eficientes e repetíveis em um ambiente automatizado.

Como Instalar e Configurar a CLI do Postman?

A CLI do Postman não é uma ferramenta independente; ela requer um ambiente configurado, geralmente com uma chave API do Postman para autenticar o acesso ao seu espaço de trabalho, coleções e ambientes. Isso é crítico para a execução segura e contínua de scripts em ambientes, especialmente ao integrar-se a plataformas de CI/CD.

Precisaremos instalar a CLI para configurá-la. A documentação do Postman possui um bom guia que pode ajudar.

Instalação no Windows

Execute os seguintes comandos para instalar a CLI do Postman para Windows. Isso baixará um script de instalação e o executará. O script de instalação cria um diretório %USERPROFILE%\AppData\Local\Microsoft\WindowsApps se ainda não existir, e então instala um binário do Postman lá.

powershell.exe -NoProfile -InputFormat None -ExecutionPolicy AllSigned -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://dl-cli.pstmn.io/install/win64.ps1'))"

Instalação no Mac (Apple silicon)

Execute o seguinte comando para instalar a CLI do Postman para Macs com processador Apple silicon. Isso baixará um script de instalação e o executará. O script de instalação cria um diretório /usr/local/bin se ainda não existir, e então instala um binário do Postman lá.

curl -o- "https://dl-cli.pstmn.io/install/osx_arm64.sh" | sh

Instalação no Mac (Intel)

Execute o seguinte comando para instalar a CLI do Postman para Macs com chips Intel. Isso baixará um script de instalação e o executará. O script de instalação cria um diretório /usr/local/bin se ainda não existir, e então instala um binário do Postman lá.

curl -o- "https://dl-cli.pstmn.io/install/osx_64.sh" | sh

Instalação no Linux

Execute o seguinte comando para instalar a CLI do Postman para a versão mais recente do Linux. Isso baixará um script de instalação e o executará. O script de instalação cria um diretório /usr/local/bin se ainda não existir, e então instala um binário do Postman lá.

curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh

Uma vez instalado, autentique-se usando sua chave API do Postman, que é gerenciada com segurança pelo backend do Postman:

postman login --with-api-key ABCD-1234-1234-1234-1234-1234

Essa gestão de chave API garante que as execuções da CLI tenham o mesmo nível de acesso e segurança que qualquer sessão na interface web ou desktop do Postman.

Executando Coleções e Ambientes

A CLI do Postman permite a execução de coleções, o coração dos testes do Postman. As coleções no Postman representam fluxos de trabalho ou sequências de chamadas de API que precisam ser testadas. Elas estão frequentemente ligadas a ambientes, que armazenam variáveis como URLs base, tokens de autenticação ou quaisquer outros detalhes de configuração que variam entre estágios de implantação (por exemplo, dev, staging, produção).

Uma das funcionalidades mais avançadas é a capacidade de executar uma coleção com um ambiente específico. Isso permite que fluxos de API complexos sejam testados em múltiplos ambientes sem modificar a própria coleção:

postman run <collection.json> --environment <environment.json>

Esse comando simples, mas poderoso, permite que múltiplas suítes de teste sejam executadas em diferentes configurações, tornando a CLI inestimável para orquestrar testes de API em pipelines de CI/CD.

Configuração Avançada: Variáveis Globais e de Ambiente

A manipulação de variáveis pela CLI do Postman é outra funcionalidade avançada. Com a introdução de ambientes dinâmicos, você pode substituir e gerenciar variáveis globais, de ambiente e locais em tempo real. Essa capacidade é essencial para fluxos de trabalho avançados em que múltiplos parâmetros de API precisam mudar dinamicamente entre diferentes fases de teste.

Considere um cenário em que sua API requer tokens de autenticação dinâmicos. Em vez de codificar tokens, você pode injetá-los dinamicamente usando a CLI do Postman:

postman run <collection.json> --env-var token=<new_token>               ‌

Em cenários mais complexos, você pode querer carregar esses valores de arquivos externos, gerenciá-los por meio dos scripts pré-solicitação da coleção do Postman, ou até mesmo passá-los como variáveis de ambiente durante a execução a partir da sua plataforma CI. Essa flexibilidade torna a CLI do Postman extremamente poderosa para lidar com fluxos de autenticação de API sofisticados.

Execução de Testes e Relatórios Personalizados

A CLI do Postman suporta a execução de coleções do Postman que contêm testes automatizados, escritos em JavaScript. Esses testes podem checar a integridade das respostas da API, validar esquemas ou comparar tempos de resposta com limites pré-definidos.

Ao executar coleções, a CLI fornece registro e relatórios detalhados. Por padrão, a saída é apresentada em um formato estruturado que mostra quais testes passaram ou falharam. No entanto, a CLI do Postman vai além do registro básico. Usuários avançados podem gerar relatórios personalizados em múltiplos formatos, incluindo JSON, HTML e JUnit XML, o que é crítico para integração com plataformas de CI como Jenkins ou GitLab:

postman run <collection.json> --reporters cli,json --reporter-json-export output.json

Esse comando não apenas executará a coleção, mas também apresentará os resultados em formatos CLI e JSON, permitindo manipulação adicional ou integração com ferramentas de dashboard.

Análise Profunda: Trabalhando com Newman vs. CLI do Postman

Antes da introdução da CLI do Postman, o Newman era a ferramenta de referência para executar coleções do Postman a partir da linha de comando. Embora o Newman continue relevante, especialmente para certos fluxos de trabalho legados, a CLI do Postman traz várias melhorias. Ela se integra diretamente com a plataforma em nuvem do Postman, oferecendo autenticação e gerenciamento de ambientes mais integrados.

Por exemplo, a CLI do Postman pode acessar espaços de trabalho compartilhados diretamente da nuvem do Postman, eliminando a necessidade de baixar e gerenciar coleções e ambientes localmente. Ela também suporta mecanismos avançados de autenticação (OAuth2, tokens de portador, etc.) nativamente por meio das configurações de espaço de trabalho do Postman, tornando-a uma solução mais robusta para fluxos de trabalho integrados em nuvem.

Aqui está uma comparação de uma execução simples de coleção usando o Newman e a CLI do Postman:

Newman:

newman run <collection.json> --environment <environment.json>

CLI do Postman:

postman run <collection>

A principal diferença aqui é a capacidade da CLI do Postman de referenciar coleções e ambientes diretamente do espaço de trabalho do Postman na nuvem, tornando-a muito mais flexível para ambientes com alta segurança ou configurações que mudam rapidamente.

Integrando a CLI do Postman em Pipelines de CI/CD

Uma das principais razões para usar a CLI do Postman é sua integração com pipelines de CI/CD. Em um pipeline, o teste automatizado de APIs se torna crucial para detectar problemas cedo no ciclo de desenvolvimento. Ferramentas como Jenkins, CircleCI, GitLab CI e GitHub Actions podem invocar comandos da CLI do Postman para executar testes de API em várias etapas do pipeline.

Considere o seguinte exemplo para integrar a CLI do Postman em um pipeline do Jenkins:

pipeline {
    agent any
    stages {
        stage('Executar Testes do Postman') {
            steps {
                script {
                    sh 'postman run <collection> --reporters cli,junit --reporter-junit-export results.xml'
                }
            }
        }
    }
    post {
        always {
            junit 'results.xml'
        }
    }
}

Esse Jenkinsfile executa a coleção do Postman e captura os resultados dos testes em um formato compatível com o plugin JUnit do Jenkins, que então gera relatórios com base nos resultados dos testes.

A CLI do Postman também permite um controle mais granular sobre a execução dos testes dentro dos pipelines. Por exemplo, você pode definir iterações específicas de suítes de teste, controlar timeouts e configurar mecanismos de repetição se um teste falhar, fornecendo um ambiente de testes altamente personalizável.

Tratando Falhas e Depurando

Testes de API podem falhar por diversas razões, desde discrepâncias no formato das respostas até configurações incorretas nos ambientes. A CLI do Postman suporta um registro detalhado, que é essencial para depurar tais problemas. Usando a flag --verbose, os desenvolvedores podem acessar uma camada profunda de informações, incluindo corpos de requisição e resposta, cabeçalhos e tempos de execução.

postman run --verbose

Quando integrada em fluxos de trabalho de CI/CD, esse nível de granularidade é inestimável. A saída detalhada pode ser enviada para logs que os desenvolvedores podem analisar para determinar se o problema está na própria API, na configuração do teste ou na configuração do ambiente.

Explorando a Apidog CLI: Uma Experiência Superior de Linha de Comando para Testes Automatizados

Enquanto a CLI do Postman é popular para automatizar fluxos de trabalho de API, Apidog CLI é uma alternativa atraente que oferece uma abordagem robusta e flexível para testes automatizados, construída especificamente para agilizar a execução de cenários de API a partir da linha de comando. O Apidog, um concorrente do Postman, oferece uma experiência de teste de API orientada por comandos, adaptada para desenvolvedores que precisam de uma solução rápida e automatizada para testar fluxos de trabalho complexos em ambientes de CI/CD.

Por que Apidog CLI?

A CLI do Apidog fornece todas as capacidades necessárias para automatizar testes de API, com um foco particular na facilidade de uso, opções de configuração avançadas e poderosas capacidades de integração. Ela é projetada para executar cenários de teste do Apidog a partir do terminal, tornando-se uma excelente escolha para equipes que desejam incorporar os testes de API diretamente em seus fluxos de trabalho de desenvolvimento e implantação. A CLI integra-se perfeitamente aos poderosos recursos em nuvem do Apidog e é otimizada para executar cenários de teste em qualquer ambiente, garantindo feedback rápido sobre a integridade das APIs em várias etapas do seu pipeline.

Configurando a Apidog CLI

Para começar a usar a Apidog CLI, certifique-se de que seu ambiente esteja equipado com Node.js versão 16 ou superior. A Apidog CLI pode ser facilmente instalada via npm, permitindo que você comece em apenas alguns comandos:

npm install -g apidog-cli

Uma vez instalada, verificar sua configuração é simples. O seguinte comando verifica sua versão do Node.js, versão da CLI e os caminhos de instalação do Node, npm e Apidog:

node -v && apidog -v && which node && which npm && which apidog

Isso garante que seu sistema esteja corretamente configurado para usar a Apidog CLI e ajuda a solucionar qualquer problema de configuração.

Executando Cenários de Teste na Apidog CLI

A Apidog CLI é projetada para executar cenários de teste de forma eficiente, fornecendo flexibilidade na forma como você autentica e executa testes. Você pode especificar um cenário de teste por seu ID exclusivo ou referenciando uma pasta que contém uma coleção de cenários de teste. Esse recurso simplifica a execução de testes de API em grande escala em múltiplos ambientes e configurações.

Veja um exemplo de execução de um cenário de teste usando um token de acesso do Apidog:

apidog run --access-token <token-de-acesso> -t <id-do-cenário-de-teste>

Esse comando executa o cenário de teste com base em seu ID, enquanto passa acreditenciais de autenticação com segurança através do token de acesso. Se você precisar executar todos os cenários de teste em uma determinada pasta, pode simplesmente usar o ID da pasta em vez disso:

apidog run --access-token <token-de-acesso> -f <id-da-pasta-do-cenário-de-teste>

Opcões Avançadas de CLI para Personalização Detalhada

Uma das forças da CLI do Apidog reside em suas opções avançadas de linha de comando. Você pode configurar relatórios de teste, variáveis de ambiente, certificados SSL e até introduzir atrasos ou timeouts entre requisições. O Apidog permite controle detalhado sobre seu processo de teste, seja quando você está executando um único cenário de teste ou um lote de testes de forma iterativa em diferentes ambientes.

Aqui está um exemplo de geração de um relatório personalizado em formatos JSON e JUnit, e salvando-o em um diretório específico:

apidog run <collection> --reporters json,junit --out-dir ./test-reports

Com a Apidog CLI, você também pode definir variáveis de ambiente dinamicamente, garantindo que seus cenários de teste sejam sensíveis ao contexto e capazes de se adaptar às mudanças nas configurações da API sem modificar os scripts principais:

apidog run <collection> --env-var "BASE_URL=https://staging.api.com" --env-var "TOKEN=abc123"

Esse tipo de flexibilidade garante que o Apidog se encaixe perfeitamente em sua infraestrutura de testes existente.

Certificados SSL e Testes de Segurança

No mundo de hoje, a validação SSL é crucial ao testar APIs. A Apidog CLI suporta a passagem de certificados de cliente, permitindo conexões seguras com suas APIs durante os testes. Se você estiver usando um único certificado ou múltiplos certificados baseados em domínios específicos, o Apidog simplifica o processo. Você pode especificar um único certificado de cliente para seus testes:

apidog run <collection> --ssl-client-cert ./caminho/para/cert.pem --ssl-client-key ./caminho/para/key.pem

Ou, para configurações mais complexas, você pode usar um arquivo JSON que contém uma lista de certificados de cliente correspondentes a URLs específicas:

apidog run <collection> --ssl-client-cert-list ./caminho/para/ssl-cert-list.json

Por que Trocar para Apidog?

A CLI do Apidog oferece uma experiência aprimorada para equipes que procuram desempenho mais rápido, integração mais fácil e mais controle sobre seus fluxos de teste de API. Ela fornece a flexibilidade de ferramentas robustas de linha de comando enquanto se integra à rica plataforma de recursos do Apidog, tornando-se uma forte alternativa à CLI do Postman.

Se você já está familiarizado com o Postman, a transição para a Apidog CLI parecerá intuitiva, mas você notará imediatamente a flexibilidade adicional e o poder que o Apidog oferece. Seu rico conjunto de recursos, combinado com relatórios extensivos e gerenciamento dinâmico de ambientes, faz do Apidog um forte candidato para desenvolvedores que precisam de uma solução de teste de API eficiente e escalável.

Conclusão

Em conclusão, enquanto o Postman tem sido um pilar no espaço de teste de APIs, a CLI do Apidog oferece uma alternativa robusta adaptada para fluxos de trabalho modernos e automatizados. Com suas opções avançadas de comando, gerenciamento de ambiente sem costura e capacidades flexíveis de relatórios, a CLI do Apidog capacita equipes a testar e validar eficientemente APIs em várias etapas de desenvolvimento e implantação. Se você está procurando uma ferramenta poderosa e flexível que se integre facilmente em seus pipelines de CI/CD, a CLI do Apidog vale a pena explorar. Ela oferece uma abordagem racionalizada para testes de API, garantindo que suas APIs permaneçam confiáveis, seguras e performáticas.