Sobre el proyecto
# Biblioteca de Cliente REST en Go
Este proyecto proporciona una biblioteca en Go y una herramienta de línea de comandos para ejecutar solicitudes HTTP definidas en archivos `.http`, el formato popularizado por los IDE de JetBrains y la extensión REST Client de VS Code. Su objetivo es la compatibilidad total con estas herramientas, permitiendo a los desarrolladores usar los mismos archivos de solicitud tanto para pruebas manuales en un IDE como para pruebas automatizadas de extremo a extremo (E2E) en Go.
## Características Clave
- **Compatibilidad con JetBrains/VS Code**: Analiza archivos `.http` usando la misma sintaxis, variables y comportamientos que las extensiones populares de IDE.
- **Sustitución de Variables**: Soporta variables personalizadas, variables de entorno y variables de sistema como `{{$guid}}`, `{{$randomInt}}`, `{{$timestamp}}` y `{{$datetime}}`.
- **Encadenamiento de Respuestas**: Referencia respuestas de otras solicitudes en el mismo archivo, por ejemplo, `{{authenticate.response.body.token}}`.
- **Referencia de Solicitudes**: Usa `@ref` (almacenado en caché por ejecución) o `@forceRef` (siempre re-ejecuta) para ejecutar solicitudes prerrequisito, y `@import` para compartir solicitudes nombradas entre archivos.
- **Control de Solicitudes**: Omite solicitudes con `@disabled`, pausa antes de enviar con `@sleep <ms>`, y repite solicitudes con `@loop`.
- **Validación de Respuestas**: Compara respuestas contra archivos `.hresp` con marcadores de posición como `{{$any}}`, `{{$regexp}}` y `{{$anyGuid}}`.
- **Múltiples Solicitudes por Archivo**: Separa solicitudes con `###`.
- **Listo para Pruebas E2E**: Diseñado para pruebas de integración automatizadas.
## Formato de Archivo HTTP
Los archivos `.http` son archivos de texto plano que definen solicitudes HTTP. Una solicitud consiste en un nombre opcional, método, URL, cabeceras y cuerpo.
```http
### Nombre de la Solicitud
MÉTODO URL
Cabecera1: valor1
contenido del cuerpo
```
### Ejemplo
```http
@baseUrl = https://api.example.com
@userId = 123
### Obtener perfil de usuario
GET {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{authToken}}
X-Request-ID: {{$guid}}
```
## Uso de la Biblioteca
### Instalación
```bash
go get github.com/bmcszk/go-restclient
```
### Ejecutar Solicitudes en Go
```go
package main
import (
"context"
"log"
"github.com/bmcszk/go-restclient"
)
func main() {
client, _ := restclient.NewClient(
restclient.WithVars(map[string]interface{}{
"authToken": "your-token-here",
}),
)
responses, _ := client.ExecuteFile(context.Background(), "requests.http")
for i, resp := range responses {
if resp.Error != nil {
log.Printf("Solicitud %d falló: %v", i+1, resp.Error)
} else {
log.Printf("Solicitud %d: %d %s", i+1, resp.StatusCode, resp.Status)
}
}
}
```
### Opciones del 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 de la CLI
La CLI `restclient` ejecuta archivos `.http` desde la línea de comandos.
### Instalación
```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 "get user"
restclient -f requests.http -i 0
restclient --version
```
### Listar Solicitudes
```bash
restclient -f requests.http --list
```
### Ejecutar una Solicitud Individual
Por nombre (sin distinción de mayúsculas):
```bash
restclient -f requests.http -n "create user"
```
Por índice basado en 0:
```bash
restclient -f requests.http -i 0
```
### Variables de Línea de Comandos
```bash
restclient -f requests.http -D token=abc123 -D env=prod
```
### Solicitudes Prerrequisito
```bash
restclient -f requests.http -n "get protected" -A authenticate
```
### Fallar en Errores
Sale con código 1 en respuestas HTTP 4xx/5xx:
```bash
restclient -f requests.http -E
```
### Formatos de Salida
```bash
# Solo cuerpo
restclient -f requests.http -o body
# Extracción de ruta JSON
restclient -f requests.http -o jsonpath "data.users[0].name"
# Formato de variable de entorno
restclient -f requests.http -o env "token"
```
### Banderas de la CLI
| Corta | Larga | Descripción |
| ----- | ---- | ----------- |
| `-f` | `--file` | Ruta del archivo de solicitud (requerido) |
| `-n` | `--name` | Ejecutar solicitud por nombre |
| `-i` | `--index` | Ejecutar solicitud por índice |
| | `--all` | Ejecutar todas las solicitudes en el archivo |
| `-e` | `--expected` | Archivo de respuesta esperada |
| | `--e-name` | Nombre de la respuesta esperada |
| | `--e-index` | Índice de la respuesta esperada |
| `-l` | `--list` | Listar solicitudes |
| `-E` | `--fail-on-error` | Fallar en 4xx/5xx |
| `-o` | `--output` | Formato de salida |
| `-A` | `--after` | Solicitud prerrequisito |
| `-D` | `--define` | Definir variable (repetible) |
## Validación de Respuestas
Crea archivos `.hresp` para validar respuestas.
**responses.hresp:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "{{$anyGuid}}",
"name": "{{$any}}",
"createdAt": "{{$anyTimestamp}}"
}
```
**Validar en Go:**
```go
err := client.ValidateResponses("responses.hresp", responses...)
if err != nil {
log.Fatal("Validación falló:", err)
}
```
### Marcadores de Posición de Validación
- `{{$any}}` - Coincide con cualquier texto
- `{{$regexp ``patrón``}}` - Patrón de expresión regular (entre comillas invertidas)
- `{{$anyGuid}}` - Formato UUID
- `{{$anyTimestamp}}` - Marca de tiempo Unix
- `{{$anyDatetime 'formato'}}` - Fecha y hora (rfc1123, iso8601 o personalizado)
## Casos de Uso
### Pruebas Manuales
Usa la extensión de tu IDE favorito para probar APIs durante el desarrollo.
### Pruebas E2E Automatizadas
```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)
}
```
## Desarrollo
### Requisitos Previos
- Go 1.21+
### Comandos
```bash
make check # Ejecuta todas las comprobaciones (lint, test, build)
```
## Licencia
Licencia MIT
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.