Démarrage rapide

De rien à un test qui passe, en cinq minutes.

Tout ce qui suit utilise l'outil en ligne de commande, gratuit et open source. L'application Mac lit les mêmes fichiers ; vous pourrez l'ajouter plus tard, ou jamais.

1. Installer

Avec Homebrew, sur macOS comme sur Linux :

$ stamp run api/orders.stamp env=staging region=latam
→ POST https://api.staging.latam.example.com/api/login  orders.stamp › logIn
  200 OK  142 ms  612 bytes
  ✓ status == 200

→ GET https://api.staging.latam.example.com/api/orders?limit=20  orders.stamp › orders
  200 OK  88 ms  4 KB
  ✓ all(body.items, o => o.total > 0)
  │ 20 orders

✓ 2 requests, 2 assertions

L'outil s'installe sous deux noms, stamp et stampdrill. C'est le même programme ; cette page écrit stamp.

2. Écrire la première requête

Créez un fichier api/orders.stamp. Une requête, c'est la ligne que vous écririez de toute façon, et en dessous les vérifications que vous gardez d'ordinaire en tête :

@base = {{host}}/api

### Log in
POST {{base}}/login
Content-Type: application/json

{ "username": "{{username}}", "password": "{{password}}" }

> assert status == 200
> set token = body.token

### Orders
@needs logIn
@auth bearer {{token}}
GET {{base}}/orders?limit=20

> assert all(body.items, o => o.total > 0)
> print length(body.items) + " orders" 

Envoyez-la avec stamp run api/orders.stamp. Les lignes qui commencent par > s'exécutent dès que la réponse arrive : assert enregistre si quelque chose est vrai, set transmet une valeur aux requêtes suivantes.

3. Des dimensions plutôt qu'une liste d'environnements

Un fichier environment.stamp nomme les axes selon lesquels votre API varie, et indique pour chaque groupe de variables où il s'applique :

dimension env = test, staging, prod
dimension region = latam, mena, apac, dach

vars {
  host = localhost(8080)
}

vars env=staging|prod {
  host = "api." + env + "." + region + ".example.com"
}

vars env=prod {
  password = secret(getenv("PROD_PASSWORD"))
}

Choisissez une valeur par axe à l'exécution : stamp run api/orders.stamp env=staging region=latam. Le jeu le plus précis l'emporte, et * signifie n'importe quelle valeur.

4. Écrire un plan de test

Un plan se place à côté des requêtes qu'il exécute. Il se répète sur une matrice de dimensions, prend des lignes de CSV ou de JSON, et donne à chaque itération sa propre session, pour qu'aucun jeton ne fuite de l'une à l'autre :

plan Checkout {
  matrix env = staging|prod, region = *
  parallel 4
  retry 2 every 500ms

  setup { run logIn }

  step "Browse" {
    run listProducts with limit = 5
    expect status == 200
    expect time < 800
    set productId = body[0].id
  }

  concurrently 10 {
    sync "go"
    run redeemCoupon with code = "WELCOME"
  }
  expect count(results, r => r.status == 200) == 1
}

stamp test . exécute les plans et sort avec un code d'erreur dès qu'une vérification échoue.

5. L'exécuter en CI

Les binaires Linux sont entièrement statiques et n'exigent rien d'autre sur la machine. Une seule étape suffit :

stamp test . --junit reports/junit.xml

Le code de sortie vaut 1 quand une vérification échoue et 2 quand un fichier ne peut pas être lu, ce qui distingue un fichier cassé d'un test en échec. Avec --html, il écrit plutôt un rapport destiné à être lu.

La suite