# Tests et oracle git

Pitmaster considère le binaire canonique `git` comme son oracle : si `git` accepte ce qu’écrit Pitmaster et que Pitmaster lit ce qu’écrit `git`, le comportement est correct. L’infrastructure de test se trouve dans le dépôt Pitmaster. Le paquet Composer ne contient que `src/` et `bin/pitmaster` ; exécutez donc les commandes ci-dessous depuis un clone après `composer install`.

## Suites de tests

| Commande | Ce qu’elle exécute | Nécessite `git` |
|---------|--------------|-------------|
| `composer test:unit` | Suite PHPUnit `unit` : tests de composants isolés | Non |
| `composer test:integration` | Suite PHPUnit `integration` : Pitmaster et `git` travaillant sur les mêmes dépôts | Oui |
| `composer test:oracle` | `bin/test-regression` : tous les scénarios oracle | Oui |
| `composer test` | PHPUnit (les deux suites) et la régression oracle | Oui |
| `./bin/verify-all` | `composer verify` : preuves de prise en charge, dérive amont, artefact de preuve, test rapide de mutation, `composer audit`, PHPStan, normes de codage et `composer test` | Oui |

CI exécute la suite unitaire sur plusieurs versions de PHP, la suite d’intégration, la régression oracle (`PITMASTER_TEST_JOBS=4`), ainsi que les vérifications des preuves de prise en charge et de la dérive amont.

## Scénarios oracle

Chaque scénario est un répertoire sous `scenarios/<category>/` (761 au total, 156 écrits pour Pitmaster et 605 importés d’autres implémentations de Git) :

```
scenarios/diff/diff-add-lines/
  scenario.json   # commands and expectations
  setup.sh        # builds the starting repository
  oracle/         # outputs captured from git
```

`scenario.json` indique la commande à exécuter avec `git` et la commande Pitmaster équivalente, ainsi que les éléments qui doivent correspondre :

```json
{
    "name": "diff-add-lines",
    "category": "diff",
    "operations": ["diff"],
    "oracle_commands": { "diff": "git -c color.ui=never diff" },
    "actual_commands": { "diff": "php \"{{ROOT}}/bin/pitmaster\" diff | perl -pe 's/\\e\\[[0-9;]*m//g'" },
    "expectations": { "exact_match": ["diff"], "fsck_clean": true }
}
```

Une exécution copie le dépôt créé par `setup.sh`, lance l’oracle et les commandes Pitmaster sur des copies distinctes, puis compare les sorties, les objets, les références et les journaux. `fsck_clean` exige également que `git fsck` accepte le dépôt écrit par Pitmaster. La sortie de l’oracle est capturée depuis `git` lorsqu’elle est absente ou actualisée ; sinon, les fichiers `oracle/` validés sont utilisés.

Un scénario couvre exactement les cas créés par sa configuration. Par exemple, les scénarios diff comparent les fichiers modifiés, ce qui explique pourquoi les différences de sortie diff pour les fichiers nouveaux, supprimés et binaires répertoriés dans [Diff](https://pitmaster.inline0.dev/fr/docs/operations/diff) ne sont pas détectées.

### Travailler avec les scénarios

```bash
./bin/test-scenario <name>                 # oracle, actual, compare for one scenario
./bin/test-regression                      # all scenarios
./bin/test-regression --jobs 4             # in parallel (or PITMASTER_TEST_JOBS=4)
./bin/test-regression --category diff      # one category
./bin/test-regression --fast               # pass/fail only, no reports

./bin/oracle <name>                        # capture git output for a scenario
./bin/oracle --refresh <name>              # re-capture, for example after a git upgrade
./bin/actual <name>                        # run Pitmaster and capture its output
./bin/compare <name>                       # compare oracle and actual output
```

Pour vérifier plusieurs versions de git, répertoriez-les dans `PITMASTER_TEST_GIT_BINARIES` et lancez le test rapide :

```bash
PITMASTER_TEST_GIT_BINARIES=/path/to/git-2.45:/path/to/git-2.46 \
  vendor/bin/phpunit --filter MultiGitVersionSmokeTest
```

## Corpus amont

Les scénarios sous `scenarios/upstream/` sont importés des suites de tests d’autres implémentations : la suite de tests de git (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7) et dulwich (6). Leurs arborescences de fixtures nécessaires sont intégrées sous `fixtures/upstream/` ; le corpus complet s’exécute ainsi depuis un nouveau checkout, sans accès réseau ni chemins propres à une machine. Les scripts de configuration les trouvent grâce à la variable d’environnement `PITMASTER_ROOT`.

`composer verify:drift` (`bin/audit-upstream-drift`) vérifie que chaque cas amont intégré correspond à un scénario.

## Matrice de prise en charge

`SUPPORT_MATRIX.md` dans le dépôt répertorie chaque fonctionnalité git concernée et son état :

| État | Signification |
|--------|---------|
| `DONE` | Implémenté et vérifié par oracle dans le périmètre de parité déclaré |
| `PART` | Partiellement implémenté |
| `TODO` | Dans le périmètre, pas encore implémenté |
| `DEFER` | Pas encore prévu |
| `N/A` | Hors périmètre |

Le fichier est généré par `bin/support-matrix` à partir de `config/support-matrix.json`. `config/support-evidence.json` associe chaque ligne `DONE` et `PART` à des tests et scénarios oracle concrets, et `composer verify:evidence` échoue lorsqu’une ligne n’a aucune preuve. CI régénère la matrice et échoue si le fichier validé diffère.

Une ligne `DONE` signifie que les scénarios qui lui sont associés correspondent à git. Le comportement peut toujours différer en dehors de ces scénarios ; les différences connues sont suivies dans le [gestionnaire de problèmes](https://github.com/inline0/pitmaster/issues).

## Benchmarks

Les optimisations de performances utilisent le harnais sous `bench/` :

```bash
composer bench -- --suite=smoke --runs=1 --warmups=0   # quick check
composer bench:baseline                                # full report
composer bench:compare -- <before.json> <after.json>   # compare two reports
composer bench:verify -- <report.json> bench/reports/smoke-thresholds.json
```

CI vérifie le rapport du test rapide par rapport aux seuils validés.