Testar API HTTP (.lnh)

Arquivo → Novo → Novo teste de API abre um cliente HTTP gravável num arquivo .lnh. Um arquivo representa um endpoint (método, URL, cabeçalhos e corpo) e guarda vários testes na lista à esquerda — cada teste com seus valores para as variáveis {nome} usadas na URL, nos cabeçalhos e no corpo, além do resultado da última execução (status, tempo, data, cabeçalhos e corpo da resposta). Mostra também o comando curl equivalente. A mesma operação pontual está disponível por CLI (http) e MCP (http_request). O testador usa o curl, que já vem no Windows 10 e 11; se ele faltar, o LightNote abre o guia de instalação antes de enviar.

Enviar e ler a resposta

Ctrl+Enter envia a requisição. Enquanto a resposta não volta, o mesmo botão vira Parar (ou Esc) e a espera mostra os segundos. O selo da resposta traz o status e o tempo; ao lado vêm o tipo, o tamanho e quando o teste rodou. A linha curl acompanha o que você digita, já com as variáveis do teste selecionado: o botão ao lado dela copia o comando, e a seta oferece o mesmo em PowerShell, Python, JavaScript, C# e HTTPie. Colar um comando curl direto na URL importa método, cabeçalhos e corpo sem apagar os testes.

Variável sem valor no teste vai literal na requisição ({id} na URL, e o servidor responde um erro que não diz por quê) — a aba Variáveis a destaca e diz o nome. O ponto ao lado de cada teste na lista tem a cor do último status, e o anel vazio é o teste que ainda não rodou. Na resposta, a barra acima do corpo formata JSON/XML só na tela, quebra linhas, copia o corpo e o salva num arquivo como veio.

Montar a requisição. A aba Parâmetros mostra a query da URL como lista: editar uma linha muda a URL, e editar a URL muda a lista. A aba Autenticação monta o cabeçalho sozinha — Basic, Bearer ou Chave de API, num cabeçalho ou na URL — e cada campo aceita {variável}, para o segredo morar no ambiente e não no arquivo; se a aba Cabeçalhos já tiver o mesmo cabeçalho, vale o que está lá. No Corpo, o Tipo escolhe JSON, XML, SOAP, formulário, multipart (campos de texto e arquivos) ou um arquivo enviado em binário, e o Content-Type entra sozinho quando você não escreveu um. Caminho de arquivo relativo conta a partir da pasta do .lnh. Com multipart ou arquivo, a seta do botão de copiar deixa PowerShell e JavaScript cinza, porque eles não sabem enviar esse corpo. A aba Opções muda o tempo-limite (60 s por padrão) e faz a requisição seguir redirecionamentos — sem isso, a resposta mostrada é o próprio 3xx. Aberto numa versão anterior do LightNote, o arquivo envia sem a autenticação e sem o tipo, e nunca uma requisição diferente. Para um servidor local com certificado próprio, Não verificar o certificado (HTTPS) desliga a verificação: enquanto estiver ligada, a linha da resposta diz certificado não verificado, e o lnote http-run também diz no relatório.

Ler a resposta. O corpo abre num editor de código só de leitura, com realce pelo tipo da resposta, dobra de blocos e a busca da janela (Ctrl+F). A aba Cookies lista o que o servidor mandou gravar, e a Linha do tempo mostra a requisição exata que saiu — com os cabeçalhos que o próprio curl acrescentou — e os cabeçalhos crus da resposta. A linha do tempo fica só na memória: ela repete o Authorization, e o arquivo vai para o Git.

Verificações

A aba Verificações diz se o teste passou. Cada linha compara uma parte da resposta — o status, um cabeçalho, o corpo inteiro, um caminho JSONPath ($.usuario.id, $.itens[0].nome, $.itens.length()), um caminho XPath (//Preco, count(//Item)) ou o tempo em milissegundos — com o valor esperado: igual, diferente, maior, menor, contém, casa com uma expressão regular, existe ou é de um tipo. No XPath o prefixo do nome é ignorado, então soap:Envelope e Envelope são o mesmo passo. Com verificações, quem decide o resultado são elas: um 404 esperado passa, e um 200 com o campo errado falha. O resultado de cada uma aparece na última coluna, o resumo vai ao lado do selo da resposta e o ponto do teste na lista fica verde ou vermelho. Desmarcar uma linha a mantém no arquivo sem contar no resultado.

O botão de tocar no topo da lista roda todos os testes do arquivo, um por vez, e diz quantos passaram. Depois que um teste roda duas vezes, o botão de comparar acima do corpo da resposta abre a execução anterior e a atual lado a lado, com o corpo formatado dos dois lados. Só a execução anterior fica guardada: o arquivo vai para o Git, e um histórico longo encheria cada diff.

Ambientes, capturas e a pasta inteira

Os ambientes usam o formato aberto do JetBrains e do VS Code: um http-client.env.json na pasta (ou acima dela) com um objeto por ambiente — {"dev": {"host": "http://localhost:8080"}} — e, ao lado, um http-client.private.env.json com os segredos, para ficar fora do Git. No mesmo ambiente o privado vence, e $shared vale para todos. O seletor ao lado da URL escolhe o ambiente, e o menu de importar e exportar cria o arquivo. Uma variável sai do teste, depois da captura, depois do ambiente, e a aba Variáveis diz de onde veio cada uma.

A aba Capturas guarda um pedaço da resposta como variável — o token de um login, o id de um recurso recém-criado — para os testes seguintes deste arquivo e dos outros da mesma pasta. É assim que um .lnh de login alimenta a chamada autenticada de outro. O valor capturado fica só na memória e nunca vai para o arquivo.

A pasta é a coleção: lnote http-run --path <pasta> --env dev roda todos os .lnh dela em ordem natural (01-login antes de 02-perfil) e sai com erro quando algum teste falha, o que serve a um CI. A mesma execução está no MCP como http_test_run, para o agente de IA rodar os testes que você escreveu. Por padrão os arquivos não mudam; --save grava neles o último resultado de cada teste.

Importar e exportar

Importar e exportar OpenAPI. O botão de setas no topo da lista de testes abre Importar OpenAPI… e Exportar OpenAPI…. A importação lê uma especificação em YAML ou JSON nas três gerações em uso — Swagger 2.0, OpenAPI 3.0 e 3.1 — e monta o teste sozinha: os {parâmetros} do caminho já são a mesma sintaxe das variáveis {nome} do .lnh, os exemplos declarados viram os valores do teste, o esquema de segurança vira o cabeçalho Authorization e cada servidor declarado vira um teste próprio (homologação e produção lado a lado). Como um .lnh guarda um endpoint, uma especificação com várias operações pergunta qual importar — ou grava todas de uma vez, um arquivo .lnh por operação.

A exportação faz o caminho inverso e gera uma especificação OpenAPI 3.0.3 a partir do arquivo: servidores, parâmetros e corpo saem do template, e as respostas de exemplo saem das execuções registradas. É um esqueleto, não um contrato completo — o .lnh descreve chamadas, então tipos, descrições e esquemas não são reconstruídos. Os seus testes viajam no campo x-lightnote-tests, e por isso voltam intactos ao reimportar o arquivo.

Importar um comando curl. No mesmo botão, Importar comando curl… abre uma caixa para colar — é de lá que o comando vem, não do disco, e o campo já vem preenchido quando há um curl na área de transferência. Entende os três dialetos em que o mesmo comando circula: o do Copiar como cURL do Chrome/Firefox (aspas simples), o do Copy as cURL (cmd) no Windows (com ^) e o exemplo de documentação quebrado com \. O método sai do -X — ou é deduzido: POST quando há corpo, GET quando não há.

A importação é literal: nenhum valor vira variável {nome} sozinho, porque adivinhar qual token é segredo erraria. Alguns casos avisam em vez de mentir — corpo vindo de arquivo (-d @arquivo) não pode ser lido, e envio multipart (-F) não é reproduzido fielmente, então os campos vão para o corpo em texto para você ajustar.

Importar de outra ferramenta. Importar de outra ferramenta… lê um arquivo .http/.rest (REST Client do VS Code, JetBrains, Visual Studio), a coleção ou o ambiente do Postman, o export do Insomnia (v4 em JSON ou v5 em YAML), o HAR que o navegador salva em Salvar tudo como HAR, o .bru do Bruno (ou a pasta inteira, por Importar pasta do Bruno…) e o WSDL de um serviço SOAP. O formato é reconhecido pelo conteúdo, não pela extensão. Cada requisição vira um .lnh e as pastas da coleção viram pastas: escolha uma para este arquivo ou grave todas de uma vez. {{nome}} vira {nome}, a autenticação vira cabeçalho, os ambientes vão para o http-client.env.json (o que a origem marca como segredo vai para o .private) sem trocar nenhum valor que já estava lá, e as verificações e capturas do Bruno — e o pm.response.to.have.status do Postman — viram verificações e capturas daqui. Do HAR saem só as chamadas de API e a página, com a resposta que o navegador recebeu como última execução; do WSDL sai um envelope SOAP por operação, com o SOAPAction e cada campo como variável.

O que não tem equivalente fica como está e é dito: scripts de pré e pós-requisição não são convertidos, variáveis dinâmicas ({{$guid}}) e encadeamentos continuam literais, e o Basic com variável, o corpo multipart e o corpo de arquivo vão para a aba Autenticação e o Tipo do corpo — com o caminho de arquivo, que veio da outra máquina, listado para conferir. Ao gravar a coleção, esse relatório vira uma nota na pasta de destino. Exportar como .http… faz o caminho inverso com o teste selecionado: o template com {{nome}} e os valores como @nome = valor.