Skip to main content
L’API sert à une chose : garder l’historique d’un côté et lancer les tests de l’autre. Utile si votre CI n’est pas GitHub Actions, ou si plusieurs dépôts partagent une même base.

Authentification

Un jeton bearer, lu dans TESTHUNCH_API_TOKEN :
Sans TESTHUNCH_API_TOKEN, l’API n’authentifie rien. C’est voulu pour le développement local, et c’est une erreur en production. Le jeton est comparé en temps constant, mais un jeton absent ne se compare à rien du tout.

Un jeton par dépôt

Le jeton de TESTHUNCH_API_TOKEN ouvre tous les dépôts : c’est celui de l’exploitant. Pour un client, une CI par exemple, on frappe un jeton qui n’ouvre qu’un dépôt, depuis la machine qui a la base :
Le secret n’est affiché qu’à sa création ; seule son empreinte SHA-256 est conservée. Aucune route de l’API ne crée de jeton : il faut la base pour en fabriquer un, donc aucune suite de requêtes, avec n’importe quel jeton, n’en produit un nouveau ni n’élargit un existant. Un jeton présenté sur un autre dépôt que le sien reçoit un 403, un jeton inconnu ou révoqué un 401. Le raisonnement est dans l’ADR 0022.

Vivacité et disponibilité

Les deux sont ouvertes, sans jeton, pour qu’un orchestrateur puisse les interroger.

Envoyer une exécution

POST /v1/runs, en multipart : un champ metadata qui contient le JSON de l’exécution, et un ou plusieurs fichiers reports.
metadata prend repo et commit_sha, tous deux obligatoires, et accepte en plus branch, base_sha et changes, la liste des fichiers modifiés. Sans changes, le classement reste possible mais ne sait rien du diff. 201 quand l’exécution est enregistrée, 200 quand les mêmes rapports pour le même commit l’étaient déjà : l’ingestion est idempotente, rejouer un job ne double pas l’historique. Les limites sont posées et renvoient 413 : 50 rapports par exécution au plus, 10 Mio par rapport. Un JSON de métadonnées invalide donne 422, un rapport illisible 400.

Demander un classement

POST /v1/prioritize, avec le dépôt et les chemins modifiés :
commit_sha n’est pas décoratif : c’est lui qui départage les scores égaux, exactement comme en ligne de commande. Le passer donne le même ordre que testhunch prioritize pour ce commit. La réponse est un objet : ranked, les tests que limit a gardés ; total, combien il y en avait en tout ; et prediction_id, non nul quand le serveur a gardé ce classement.

Faire garder le classement au serveur

Avec "record": true, le serveur conserve le classement qu’il vient de servir, pour que le mode fantôme puisse le comparer au run qui suivra. Il faut alors commit_sha : un classement qui ne dit pas ce qu’il prédit ne se compare à rien, et sans lui la réponse est 422. Le client n’envoie jamais de classement. Le serveur enregistre ce qu’il a servi, et lui seul. Autrement, n’importe quel client pourrait enregistrer une prédiction que le serveur n’a pas faite, et un rapport de mode fantôme ne vaut que si personne n’a pu écrire la prédiction après avoir vu le résultat (ADR 0023).

Lire le rapport

GET /v1/report?repo=acme/shop renvoie les tests instables, lents et en échec, comme la commande du même nom, plus le nombre d’exécutions enregistrées. Deux paramètres facultatifs : last_runs, le nombre d’exécutions récentes couvertes (50 par défaut), et limit, le nombre de lignes par section (10 par défaut).