Lançamento do Hurl 4.0.0

• Hurl 4.0.0 é a nova versão da ferramenta de teste HTTP em CLI baseada em curl, aprimorando o fluxo de execução de requisições HTTP e validações de resposta escritas em arquivos de texto puro
• O relatório HTML é gerado como HTML puro, usando apenas CSS inline e sem JavaScript, exibindo junto linha do tempo em cascata por requisição/resposta, log de execução e erros inline
• --error-format long imprime os cabeçalhos e o corpo da resposta de testes que falharam, permitindo verificar o contexto necessário para identificar a causa em depuração de CI/CD sem precisar executar novamente
• Com os novos filtros decode e xpath, é possível decodificar diretamente bytes de resposta com charset indefinido e realizar validações XPath sobre partes de HTML
• Parte da forma de avaliação do JSONPath mudou, e agora há suporte a métodos HTTP customizados que atendam à condição de letras maiúsculas, permitindo experimentar novos métodos como QUERY

---

Visão geral do Hurl 4.0.0

• Hurl é uma ferramenta de linha de comando baseada em curl que executa requisições HTTP definidas em um formato simples de texto puro
• Em arquivos Hurl, é possível escrever junto a requisição, o status HTTP esperado e validações (asserts) como cabeçalhos, certificados e JSONPath
• Hurl 4.0.0 traz mudanças principalmente em relatório HTML, saída de erros, filtros, comportamento do JSONPath e suporte a métodos HTTP customizados

Relatório HTML e linha do tempo em cascata

• O Hurl HTML report gera três tipos de informação a cada execução
  • Linha do tempo em cascata: mostra cada requisição/resposta em gráfico e permite verificar tempos de resposta como DNS, handshake TCP e time to first byte
  • Log de execução: inclui cabeçalhos de requisição/resposta e informações de certificado
  • Arquivo-fonte com destaque de sintaxe: mostra erros inline
• O relatório é composto por HTML puro e CSS inline, sem JavaScript, o que facilita a integração em ambientes de CI/CD como GitLab CI/CD e GitHub Actions
• Os tempos usados na linha do tempo em cascata são fornecidos pelo libcurl e também ficam disponíveis pela opção --json
  • --json fornece informações estruturadas da execução, incluindo erros, asserts, certificados, capturas, cookies e tempos
  • Com essa saída JSON, é possível criar relatórios próprios

Gargalo de desempenho de asserts revelado pela visualização

• Visualizações ricas podem revelar problemas de desempenho ocultos
• Em algumas execuções, apareceu um grande intervalo entre requisições, e a causa era a quantidade muito alta de asserts sobre a resposta HTTP
• No Hurl 4.0.0, o cálculo de asserts funciona de forma simples
  • Cada assert da mesma resposta é processado de forma independente
  • A cada assert, o parsing começa do zero e tudo é recalculado
• A equipe do Hurl confiava na velocidade da combinação de libcurl com Rust, mas esse caso levou à conclusão de que a próxima versão precisa de melhorias de desempenho nos asserts

Saída detalhada de erros para CI/CD

• A saída anterior de falhas de teste era centrada no valor esperado, então podia faltar informação para análise
• A nova opção --error-format permite escolher descrições de erro mais longas
• No modo --error-format long, os cabeçalhos e o corpo da resposta são registrados automaticamente no log
• No exemplo, o teste procurava o cabeçalho Control-Security-Policy, mas a resposta real continha Content-Security-Policy
  • Como os cabeçalhos e o corpo da resposta ficam no log, fica fácil identificar esse tipo de erro por digitação
• Essa opção é útil em ambientes de CI/CD quando se quer obter o contexto necessário para depuração da sessão sem executar o teste novamente
• Como até o corpo da resposta é registrado, o log pode ficar muito longo

Novos filtros: decode e xpath

• Os asserts de texto do Hurl decodificam automaticamente os bytes do corpo da resposta usando a dica de charset do cabeçalho de resposta Content-Type
• Em alguns casos, o Content-Type não informa a codificação, ou o charset está presente em uma tag <meta> dentro do documento HTML
• O novo filtro decode permite decodificar explicitamente bytes em texto para validação
  • O exemplo decodifica um corpo codificado em GB2312 com bytes decode "gb2312"
• O novo filtro xpath permite avaliar expressões XPath sobre partes da resposta
  • O exemplo valida o texto do body em HTML com xpath "string(//body)"

Mudanças na forma de avaliação do JSONPath

• O Hurl 4.0.0 altera parte da avaliação de consultas JSONPath
• O JSONPath não tem uma especificação oficial adequada, e o Hurl tenta seguir o máximo possível a documentação de goessner.net, usada na prática como padrão
• Existem casos extremos diferentes entre implementações
  • O JSONPath padrão sempre retorna coleções, mas na maioria dos casos isso não tem muito significado e pode dificultar os testes
  • Algumas implementações distinguem entre o valor do nó em definite path e a coleção em indefinite path
• No Hurl 4.0.0, existem apenas dois tipos de selector que retornam valor
  • Selector de índice de array: $.store.book[2]
  • Selector de chave de objeto: $.store.bicycle.color, $.store.bicycle['color']
• Selectors com filtro ou selectors como $[*].id retornam coleções
  • Para extrair um valor da coleção, é possível usar o filtro nth

Métodos HTTP customizados

• O Hurl 4.0.0 suporta métodos HTTP customizados arbitrários
• Os métodos devem ser escritos em letras maiúsculas
• Como exemplo, já é possível experimentar imediatamente o novo método QUERY
  • Documento relacionado: incoming new QUERY method

Notas de lançamento e pedido de participação

• Outras melhorias e correções de bugs podem ser consultadas na release note
• O projeto pede GitHub star, compartilhamento no Twitter, pedidos de melhorias e compartilhamento de casos de uso

[GN⁺]

Comentários do Hacker News

• Gostei que a apresentação do Hurl começa com “uma ferramenta de linha de comando baseada em curl que executa requisições HTTP definidas em um formato simples de texto puro”
  Foi a primeira vez que vi o Hurl, e só com a introdução curta e o exemplo de código no topo já tive vontade de instalar e testar na hora; parece um excelente lançamento

  • Como mantenedor do Hurl, depois de ler Hacker News por muito tempo, fui anotando todos os conselhos de apresentação como “mostre exemplos da linguagem o mais rápido possível” e “explique o conceito de forma concisa sempre”, e tentei aplicar isso de fato no hurl.dev
  • Posts de anúncio e READMEs demais começam falando de requisitos de instalação ou de “corrigimos X, Y, Z”, mas não explicam o que a ferramenta faz; esse jeito aqui está certo
  • Verdade, mas a maior parte disso deveria estar no título do post
    Por exemplo, um título como Hurl: Run HTTP requests in a simple plain-text format teria sido melhor

• Queria que isso virasse o padrão da indústria para testes de API
  Já cansei de ver captura de tela do Postman enviada pelo QA e de esperar o QA apertar Send depois de cada correção; e o QA provavelmente também cansou de esperar os desenvolvedores
  O Hurl pode ser lido e escrito tanto por devs quanto por QA, permite automação e integração com CI, facilita transmitir o comportamento esperado e pode entrar junto no PR como ponto de partida para o QA, então parece não haver motivo para não usar onde for possível

  • Estamos usando Hurl para testes manuais de API e também no CI em um serviço, e tem funcionado muito bem
    Dá para colocar o fluxo de trocas HTTP de cada workflow em um único arquivo hurl, e isso vira uma suíte de testes que entra direto no Git
  • Se sua equipe usa VSCode, talvez também valha testar o vscode-restclient: https://github.com/Huachao/vscode-restclient
    Dito isso, o Hurl também é muito interessante, e concordo que ser independente do editor é uma solução melhor para esse problema
  • Fico curioso se você já usou https://k6.io/
    Você escreve testes de carga/desempenho em JS, faz commit no repositório, automatiza facilmente no CI, envia métricas para vários backends, usa protocolos além de HTTP e ainda tem uma interface moderna de linha de comando com vários recursos
    Também existe um conversor de Postman para k6: https://github.com/apideck-libraries/postman-to-k6
    A filosofia do k6 é que desenvolvedores escrevam esse tipo de teste, como fazem com testes unitários/de integração, para quebrar o ciclo clássico entre QA e desenvolvimento; o Hurl também parece ótimo, mas é mais limitado em recursos do que ferramentas já existentes de teste de performance e, pessoalmente, prefiro escrever testes em uma linguagem de programação em vez de um formato de texto dedicado
  • Pessoalmente, gosto mais da abordagem de definir tudo em OpenAPI e depois validar a especificação com Dredd
    Mesmo usando uma ferramenta que gera a especificação a partir do código-fonte, ainda é possível errar na definição dos metadados dos endpoints, e o Dredd pega isso

• Parece um dos melhores exemplos de programa Unix moderno que já vi até agora
  Lê da entrada padrão, escreve na saída padrão, não enche o terminal de emoji Unicode por toda parte, e ainda tem páginas man bem feitas
  Também gostei que a extensão de arquivo do hurl tem quatro letras em vez de três; finalmente parece que deixamos de nos preocupar com compatibilidade com MS-DOS
  Parece uma ferramenta que vale considerar seriamente

  • Eu nem percebia o quanto os emojis no terminal me incomodavam, mas só ler que essa ferramenta não faz isso já me deixou contente
  • Não só compatibilidade com MS-DOS, mas também com VMS

• Entre as ferramentas de linha de comando para lidar com HTTP, minhas favoritas são Httpie ou XH, a reescrita mais rápida em Rust
  Dá para enviar requisições pela linha de comando com uma sintaxe muito mais próxima de HTTP do que curl, sem precisar aprender um monte de opções
  Se você já domina curl, talvez isso não sirva para muita coisa, mas para uso casual é bem mais intuitivo
  https://httpie.io/
  https://github.com/ducaale/xh

• Na Adaptive, estamos usando hurl.dev amplamente para automação de testes: https://adaptive.live
  Testamos fluxos internos inteiros do produto com Hurl, e foi uma das melhores decisões que adotamos na organização em termos de estabilização do produto
  Antes de cada deploy, rodamos vários testes automatizados baseados em Hurl para validar onboarding, cadastro, fluxos principais etc., e como tudo é containerizado, também dá para executar em paralelo
  Também estamos criando ferramentas internas em torno do hurl.dev, e gostamos do fato de ser fácil de aprender, então analistas e usuários de negócio também conseguem criar testes

  • Fico curioso sobre o motivo de usar uma ferramenta independente
    Em contexto de testes, uma abordagem baseada em navegador como Selenium parece muito mais poderosa e útil no geral
  • Gostaria de saber se ele oferece suporte nativo a fluxos OAuth ou se exige tokens hardcoded
    Dei uma olhada na documentação, mas não encontrei nada sobre isso

• Estou acompanhando o hurl há algum tempo, e o ponto que o diferencia de outras ferramentas é ter uma DSL própria para testes
  Ele não só faz requisições HTTP, como também valida respostas e captura dados
  Mas, se o mantenedor estiver lendo, eu gostaria que fosse possível delegar validações para scripts externos
  Por exemplo, para validar que todas as propriedades de uma coleção de itens têm o mesmo valor, isso ainda é difícil sem usar o seletor nth, e algo como nth = * também seria necessário
  Cobrir todos os casos de uso na DSL é um trabalho grande demais, então seria ótimo se fosse possível passar o resultado do jsonpath para jq e considerar o teste aprovado se ele retornar true

  • Uma DSL inevitavelmente tende a crescer até virar uma linguagem de propósito geral Turing-completa, então chamar scripts externos parece razoável
    Dito isso, isso também pode tornar os arquivos menos autocontidos e trazer problemas bem complicados

• O Hurl parece estar crescendo rápido, o que é animador
  Em testes de endpoint, sempre precisamos de autenticação, então fico curioso se existe uma forma de escrever a autenticação em um arquivo e depois importá-la no começo de outros arquivos que precisam do token

  • Pelo que vejo, o Hurl não parece ter recursos como include ou macros
    E também não sei se esse seria mesmo o melhor jeito de armazenar e usar segredos
    Segundo a documentação, é possível passar variáveis para os arquivos hurl por argumentos de linha de comando e variáveis de ambiente: https://hurl.dev/docs/templates.html

• Para esse uso, também gosto bastante do httpyac: https://httpyac.github.io
  Ele tem recursos de script em JS, então é bastante parecido, e além da interface de linha de comando, a integração com VS Code também é excelente

  • O httpyac também tem boa compatibilidade com o suporte a .http das IDEs da JetBrains
    A JetBrains também oferece uma ferramenta gratuita de linha de comando que gera relatórios de teste jUnit a partir de arquivos .http

• Descobri que o Visual Studio 2022 também oferece algo parecido com arquivos .http: https://learn.microsoft.com/en-us/aspnet/core/test/http-file...
  O Hurl parece ter muito mais recursos

  • As IDEs da JetBrains também oferecem suporte a isso, então por enquanto parece um formato de certa forma mais próximo de um padrão do que outras alternativas
  • O Hurl é muito mais rápido
  • Já uso há um tempo a extensão do VS Code na qual esse recurso se baseou