> ## Documentation Index
> Fetch the complete documentation index at: https://testhunch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# L'Action GitHub

> Classer avant les tests, enregistrer après, et lire le résumé dans la page du job.

L'Action fait deux choses et rien d'autre : `prioritize` avant vos tests, `ingest` après. **Elle ne
saute aucun test.** Sauter se décide ailleurs, et volontairement (voir
[le filet de sécurité](https://testhunch.mintlify.site/docs/ci/filet-de-securite.md)).

## Un workflow complet

```yaml theme={"system"}
- uses: actions/checkout@v7
  with:
    fetch-depth: 0 # testhunch compare avec la branche de base de la pull request

- id: testhunch
  uses: amazing-source/testhunch@v0.6.0
  with:
    command: prioritize
    database-url: ${{ secrets.TESTHUNCH_DATABASE_URL }}

- run: pytest --junitxml=junit.xml

- if: ${{ !cancelled() }}
  uses: amazing-source/testhunch@v0.6.0
  with:
    command: ingest
    reports: junit.xml
    database-url: ${{ secrets.TESTHUNCH_DATABASE_URL }}
```

> [!WARNING]
>
> Le `if: ${{ !cancelled() }}` compte. Sans lui, l'étape `ingest` est sautée quand les tests échouent,
> c'est-à-dire précisément quand il y a quelque chose à apprendre.

## Les entrées

| Entrée | Rôle |
| - | - |
| `command` | `prioritize` ou `ingest`. Toute autre valeur arrête le job avec une erreur claire. |
| `reports` | Pour `ingest` : fichiers JUnit XML ou motifs glob, un par ligne. |
| `base` | Référence à comparer pour trouver les fichiers modifiés. Par défaut, la branche de base sur un événement `pull_request`, et rien sinon. |
| `database-url` | Où garder l'historique. Par défaut un fichier SQLite dans l'espace de travail, qui disparaît avec le job. |
| `api-url` | Pour `ingest` : envoyer le run à un testhunch hébergé au lieu d'une base. Le jeton vient de `TESTHUNCH_API_TOKEN`, posé en variable d'environnement de l'étape. |
| `last` | Pour `ingest` : sur combien d'exécutions récentes portent les résumés (50 par défaut). Le classement, lui, apprend de tous les builds enregistrés. |
| `summary-limit` | Pour `prioritize` : combien de tests afficher dans le résumé du job (20 par défaut). |
| `record` | Pour `prioritize` : enregistrer le classement pour le mode fantôme (`true` par défaut). |

Les motifs glob sont transmis entre guillemets et développés par testhunch lui-même, pas par le
shell du runner. Le même motif donne donc les mêmes fichiers sur Linux, macOS et Windows.

## Les sorties

`prioritize` produit deux fichiers :

* **`ranking-json`** : le chemin d'un JSON avec chaque test, son score et ses raisons ;
* **`ranking-keys`** : le chemin d'un fichier texte, une clé de test par ligne, du plus au moins
  susceptible d'échouer.

```yaml theme={"system"}
- run: head -20 "${{ steps.testhunch.outputs.ranking-keys }}"
```

## Ce que vous verrez dans le job

`prioritize` écrit les tests les mieux classés dans le résumé du job. `ingest` y écrit deux choses :
le rapport des tests instables, lents et en échec, puis le rapport du mode fantôme, c'est-à-dire ce
que sauter les tests les moins bien classés aurait manqué. Sur les premiers builds, ce dernier n'a
rien à dire, il lui faut de l'historique.

## Garder l'historique

Sans `database-url`, l'historique ne survit pas d'une exécution à l'autre, et testhunch repart de
zéro à chaque job. C'est utile pour essayer, inutile pour s'en servir. Pour un vrai usage, passez
l'URL d'une base Postgres depuis un secret.

## Sur la version

L'Action construit le paquet **depuis son propre checkout**, donc `@v0.6.0` fait tourner
testhunch 0.6.0 : l'Action et la CLI ne peuvent pas diverger. Pour une garantie plus forte qu'un tag,
épinglez le SHA du commit.

> [!NOTE]
>
> Les entrées arrivent au script par des variables d'environnement, jamais interpolées dans un `run:`.
> Une valeur fabriquée ne peut donc pas exécuter de commandes sur votre runner.

## Envoyer à un testhunch hébergé

Au lieu d'une base que votre job doit joindre, `api-url` envoie le run au service :

```yaml theme={"system"}
- if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
  uses: amazing-source/testhunch@v0.6.0
  env:
    TESTHUNCH_API_TOKEN: ${{ secrets.TESTHUNCH_API_TOKEN }}
  with:
    command: ingest
    reports: junit.xml
    api-url: https://api.exemple.fr
```

Les rapports partent tels quels et c'est le serveur qui les analyse. Une adresse en `http://` qui
n'est pas la boucle locale est refusée, pour que le jeton ne circule jamais en clair. Demandez à
l'exploitant du service un jeton qui n'ouvre que votre dépôt plutôt que le sien, qui les ouvre tous.

Avec `api-url`, `prioritize` demande aussi le classement au serveur, qui **garde ce qu'il a servi**
quand `record` est actif. Le classement et le run qui suit vivent donc dans la même base, et le mode
fantôme a de quoi comparer ([ADR 0023](https://github.com/amazing-source/testhunch/blob/main/docs/adr/0023-the-server-keeps-the-ranking-it-served.md)).

Le résumé du job montre alors le rapport du mode fantôme tel que le serveur le calcule : c'est chez
lui que vivent les deux moitiés qu'il compare, le classement qu'il a servi et les résultats qu'on
lui a envoyés.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.