À propos du projet
# Bibliothèque client REST Go
Ce projet fournit une bibliothèque Go et un outil en ligne de commande pour exécuter des requêtes HTTP définies dans des fichiers `.http`, le format popularisé par les IDE JetBrains et l'extension REST Client de VS Code. Il vise une compatibilité totale avec ces outils, permettant aux développeurs d'utiliser les mêmes fichiers de requêtes pour les tests manuels dans un IDE et les tests de bout en bout (E2E) automatisés en Go.
## Fonctionnalités clés
- **Compatibilité JetBrains/VS Code** : Analyse les fichiers `.http` en utilisant la même syntaxe, les mêmes variables et les mêmes comportements que les extensions IDE populaires.
- **Substitution de variables** : Prend en charge les variables personnalisées, les variables d'environnement et les variables système comme `{{$guid}}`, `{{$randomInt}}`, `{{$timestamp}}` et `{{$datetime}}`.
- **Chaînage de réponses** : Référencez les réponses d'autres requêtes dans le même fichier, par exemple `{{authenticate.response.body.token}}`.
- **Référencement de requêtes** : Utilisez `@ref` (mis en cache par exécution) ou `@forceRef` (toujours réexécuté) pour exécuter des requêtes préalables, et `@import` pour partager des requêtes nommées entre fichiers.
- **Contrôle des requêtes** : Ignorez les requêtes avec `@disabled`, faites une pause avant l'envoi avec `@sleep <ms>`, et bouclez les requêtes avec `@loop`.
- **Validation des réponses** : Comparez les réponses avec des fichiers `.hresp` contenant des espaces réservés comme `{{$any}}`, `{{$regexp}}` et `{{$anyGuid}}`.
- **Plusieurs requêtes par fichier** : Séparez les requêtes avec `###`.
- **Prêt pour les tests E2E** : Conçu pour les tests d'intégration automatisés.
## Format de fichier HTTP
Les fichiers `.http` sont des fichiers texte brut définissant des requêtes HTTP. Une requête se compose d'un nom optionnel, d'une méthode, d'une URL, d'en-têtes et d'un corps.
```http
### Nom de la requête
MÉTHODE URL
En-tête1: valeur1
contenu du corps
```
### Exemple
```http
@baseUrl = https://api.example.com
@userId = 123
### Obtenir le profil utilisateur
GET {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{authToken}}
X-Request-ID: {{$guid}}
```
## Utilisation de la bibliothèque
### Installation
```bash
go get github.com/bmcszk/go-restclient
```
### Exécuter des requêtes en Go
```go
package main
import (
"context"
"log"
"github.com/bmcszk/go-restclient"
)
func main() {
client, _ := restclient.NewClient(
restclient.WithVars(map[string]interface{}{
"authToken": "votre-jeton-ici",
}),
)
responses, _ := client.ExecuteFile(context.Background(), "requests.http")
for i, resp := range responses {
if resp.Error != nil {
log.Printf("Requête %d échouée : %v", i+1, resp.Error)
} else {
log.Printf("Requête %d : %d %s", i+1, resp.StatusCode, resp.Status)
}
}
}
```
### Options du client
```go
client, err := restclient.NewClient(
restclient.WithBaseURL("https://api.example.com"),
restclient.WithDefaultHeader("X-API-Key", "secret"),
restclient.WithHTTPClient(customHTTPClient),
restclient.WithVars(variables),
)
```
## Utilisation du CLI
Le CLI `restclient` exécute des fichiers `.http` depuis la ligne de commande.
### Installation
```bash
go install github.com/bmcszk/go-restclient/cmd/restclient@latest
```
### Commandes de base
```bash
restclient -f requests.http --all
restclient -f requests.http -n "get user"
restclient -f requests.http -i 0
restclient --version
```
### Lister les requêtes
```bash
restclient -f requests.http --list
```
### Exécuter une seule requête
Par nom (insensible à la casse) :
```bash
restclient -f requests.http -n "create user"
```
Par index basé sur 0 :
```bash
restclient -f requests.http -i 0
```
### Variables de ligne de commande
```bash
restclient -f requests.http -D token=abc123 -D env=prod
```
### Requêtes préalables
```bash
restclient -f requests.http -n "get protected" -A authenticate
```
### Échec en cas d'erreur
Sortie avec le code 1 en cas de réponses HTTP 4xx/5xx :
```bash
restclient -f requests.http -E
```
### Formats de sortie
```bash
# Corps uniquement
restclient -f requests.http -o body
# Extraction de chemin JSON
restclient -f requests.http -o jsonpath "data.users[0].name"
# Format de variable d'environnement
restclient -f requests.http -o env "token"
```
### Options du CLI
| Court | Long | Description |
| ----- | ---- | ----------- |
| `-f` | `--file` | Chemin du fichier de requêtes (obligatoire) |
| `-n` | `--name` | Exécuter la requête par nom |
| `-i` | `--index` | Exécuter la requête par index |
| | `--all` | Exécuter toutes les requêtes du fichier |
| `-e` | `--expected` | Fichier de réponse attendue |
| | `--e-name` | Nom de la réponse attendue |
| | `--e-index` | Index de la réponse attendue |
| `-l` | `--list` | Lister les requêtes |
| `-E` | `--fail-on-error` | Échouer sur 4xx/5xx |
| `-o` | `--output` | Format de sortie |
| `-A` | `--after` | Requête préalable |
| `-D` | `--define` | Définir une variable (répétable) |
## Validation des réponses
Créez des fichiers `.hresp` pour valider les réponses.
**responses.hresp :**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "{{$anyGuid}}",
"name": "{{$any}}",
"createdAt": "{{$anyTimestamp}}"
}
```
**Valider en Go :**
```go
err := client.ValidateResponses("responses.hresp", responses...)
if err != nil {
log.Fatal("Échec de la validation :", err)
}
```
### Espaces réservés de validation
- `{{$any}}` - Correspond à tout texte
- `{{$regexp ``pattern``}}` - Modèle d'expression régulière (entre accents graves)
- `{{$anyGuid}}` - Format UUID
- `{{$anyTimestamp}}` - Horodatage Unix
- `{{$anyDatetime 'format'}}` - Date et heure (rfc1123, iso8601 ou personnalisé)
## Cas d'utilisation
### Tests manuels
Utilisez l'extension IDE de votre choix pour tester les API pendant le développement.
### Tests E2E automatisés
```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)
}
```
## Développement
### Prérequis
- Go 1.21+
### Commandes
```bash
make check # Exécute toutes les vérifications (lint, test, build)
```
## Licence
Licence MIT
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.