Sobre o projeto

# Biblioteca Cliente REST em Go Este projeto fornece uma biblioteca Go e uma ferramenta de linha de comando para executar requisições HTTP definidas em arquivos `.http`, o formato popularizado pelos IDEs JetBrains e pela extensão REST Client do VS Code. Ele visa total compatibilidade com essas ferramentas, permitindo que os desenvolvedores usem os mesmos arquivos de requisição tanto para testes manuais em um IDE quanto para testes automatizados de ponta a ponta (E2E) em Go. ## Principais Recursos - **Compatibilidade com JetBrains/VS Code**: Analisa arquivos `.http` usando a mesma sintaxe, variáveis e comportamentos das extensões populares de IDE. - **Substituição de Variáveis**: Suporta variáveis personalizadas, variáveis de ambiente e variáveis de sistema como `{{$guid}}`, `{{$randomInt}}`, `{{$timestamp}}` e `{{$datetime}}`. - **Encadeamento de Respostas**: Referencie respostas de outras requisições no mesmo arquivo, por exemplo, `{{authenticate.response.body.token}}`. - **Referência a Requisições**: Use `@ref` (armazenado em cache por execução) ou `@forceRef` (sempre reexecuta) para executar requisições pré-requisito, e `@import` para compartilhar requisições nomeadas entre arquivos. - **Controle de Requisições**: Pule requisições com `@disabled`, pause antes de enviar com `@sleep <ms>` e repita requisições com `@loop`. - **Validação de Respostas**: Compare respostas com arquivos `.hresp` usando placeholders como `{{$any}}`, `{{$regexp}}` e `{{$anyGuid}}`. - **Múltiplas Requisições por Arquivo**: Separe requisições com `###`. - **Pronto para Testes E2E**: Projetado para testes de integração automatizados. ## Formato do Arquivo HTTP Arquivos `.http` são arquivos de texto simples que definem requisições HTTP. Uma requisição consiste em um nome opcional, método, URL, cabeçalhos e corpo. ```http ### Nome da Requisição MÉTODO URL Cabeçalho1: valor1 conteúdo do corpo ``` ### Exemplo ```http @baseUrl = https://api.example.com @userId = 123 ### Obter perfil do usuário GET {{baseUrl}}/users/{{userId}} Authorization: Bearer {{authToken}} X-Request-ID: {{$guid}} ``` ## Uso da Biblioteca ### Instalação ```bash go get github.com/bmcszk/go-restclient ``` ### Executar Requisições em Go ```go package main import ( "context" "log" "github.com/bmcszk/go-restclient" ) func main() { client, _ := restclient.NewClient( restclient.WithVars(map[string]interface{}{ "authToken": "seu-token-aqui", }), ) responses, _ := client.ExecuteFile(context.Background(), "requests.http") for i, resp := range responses { if resp.Error != nil { log.Printf("Requisição %d falhou: %v", i+1, resp.Error) } else { log.Printf("Requisição %d: %d %s", i+1, resp.StatusCode, resp.Status) } } } ``` ### Opções do Cliente ```go client, err := restclient.NewClient( restclient.WithBaseURL("https://api.example.com"), restclient.WithDefaultHeader("X-API-Key", "secret"), restclient.WithHTTPClient(customHTTPClient), restclient.WithVars(variables), ) ``` ## Uso da CLI A CLI `restclient` executa arquivos `.http` a partir da linha de comando. ### Instalação ```bash go install github.com/bmcszk/go-restclient/cmd/restclient@latest ``` ### Comandos Básicos ```bash restclient -f requests.http --all restclient -f requests.http -n "obter usuário" restclient -f requests.http -i 0 restclient --version ``` ### Listar Requisições ```bash restclient -f requests.http --list ``` ### Executar uma Única Requisição Por nome (insensível a maiúsculas/minúsculas): ```bash restclient -f requests.http -n "criar usuário" ``` Por índice baseado em 0: ```bash restclient -f requests.http -i 0 ``` ### Variáveis de Linha de Comando ```bash restclient -f requests.http -D token=abc123 -D env=prod ``` ### Requisições Pré-requisito ```bash restclient -f requests.http -n "obter protegido" -A autenticar ``` ### Falhar em Erros Saia com código 1 em respostas HTTP 4xx/5xx: ```bash restclient -f requests.http -E ``` ### Formatos de Saída ```bash # Apenas corpo restclient -f requests.http -o body # Extração de caminho JSON restclient -f requests.http -o jsonpath "data.users[0].name" # Formato de variável de ambiente restclient -f requests.http -o env "token" ``` ### Flags da CLI | Curto | Longo | Descrição | | ----- | ---- | ----------- | | `-f` | `--file` | Caminho do arquivo de requisição (obrigatório) | | `-n` | `--name` | Executar requisição por nome | | `-i` | `--index` | Executar requisição por índice | | | `--all` | Executar todas as requisições no arquivo | | `-e` | `--expected` | Arquivo de resposta esperada | | | `--e-name` | Nome da resposta esperada | | | `--e-index` | Índice da resposta esperada | | `-l` | `--list` | Listar requisições | | `-E` | `--fail-on-error` | Falhar em 4xx/5xx | | `-o` | `--output` | Formato de saída | | `-A` | `--after` | Requisição pré-requisito | | `-D` | `--define` | Definir variável (repetível) | ## Validação de Respostas Crie arquivos `.hresp` para validar respostas. **responses.hresp:** ```http HTTP/1.1 200 OK Content-Type: application/json { "id": "{{$anyGuid}}", "name": "{{$any}}", "createdAt": "{{$anyTimestamp}}" } ``` **Validar em Go:** ```go err := client.ValidateResponses("responses.hresp", responses...) if err != nil { log.Fatal("Falha na validação:", err) } ``` ### Placeholders de Validação - `{{$any}}` - Corresponde a qualquer texto - `{{$regexp ``padrão``}}` - Padrão regex (entre crases) - `{{$anyGuid}}` - Formato UUID - `{{$anyTimestamp}}` - Timestamp Unix - `{{$anyDatetime 'formato'}}` - Data e hora (rfc1123, iso8601 ou personalizado) ## Casos de Uso ### Testes Manuais Use a extensão do seu IDE favorito para testar APIs durante o desenvolvimento. ### Testes E2E Automatizados ```go func TestUserAPI(t *testing.T) { client, _ := restclient.NewClient( restclient.WithBaseURL(testServer.URL), ) responses, err := client.ExecuteFile(context.Background(), "user_tests.http") require.NoError(t, err) err = client.ValidateResponses("user_expected.hresp", responses...) require.NoError(t, err) } ``` ## Desenvolvimento ### Pré-requisitos - Go 1.21+ ### Comandos ```bash make check # Executa todas as verificações (lint, teste, build) ``` ## Licença Licença MIT