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

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 :

{
    "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 ne sont pas détectées.

Travailler avec les scénarios

./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 :

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 :

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.

Benchmarks

Les optimisations de performances utilisent le harnais sous bench/ :

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.