Testen en de git-oracle

Pitmaster gebruikt de canonieke git-binary als oracle: als git accepteert wat Pitmaster schrijft en Pitmaster leest wat git schrijft, klopt het gedrag. De testinfrastructuur staat in de Pitmaster-repository. Het Composer-pakket bevat alleen src/ en bin/pitmaster. Voer al het onderstaande uit vanuit een clone nadat je composer install hebt uitgevoerd.

Testsuites

CI voert de unittestsuite uit op verschillende versies van PHP, de integratiesuite, de oracle-regressietest (PITMASTER_TEST_JOBS=4) en de controles voor ondersteuningsbewijs en upstream-afwijkingen.

Oracle-scenario's

Elk scenario is een map onder scenarios/<category>/ (in totaal 761: 156 geschreven voor Pitmaster en 605 geïmporteerd uit andere Git-implementaties):

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

scenario.json vermeldt de uit te voeren opdracht met git en de equivalente Pitmaster-opdracht, en wat moet overeenkomen:

{
    "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 }
}

Een uitvoering kopieert de repository die door setup.sh is opgebouwd, voert de oracle en de opdrachten van Pitmaster uit op afzonderlijke kopieën en vergelijkt de uitvoer, objecten, refs en log. fsck_clean vereist ook dat git fsck de repository accepteert die Pitmaster heeft geschreven. De oracle-uitvoer wordt vastgelegd vanuit git als die ontbreekt of wordt vernieuwd; anders worden de vastgelegde bestanden van oracle/ gebruikt.

Een scenario dekt precies de gevallen die bij de setup worden opgebouwd. De diff-scenario's vergelijken bijvoorbeeld gewijzigde bestanden. Daarom worden de verschillen in diff-uitvoer voor nieuwe, verwijderde en binaire bestanden die in Diff staan, er niet door gedetecteerd.

Werken met scenario's

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

Als je meerdere git-versies wilt controleren, vermeld je ze in PITMASTER_TEST_GIT_BINARIES en voer je de smoketest uit:

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

Upstream-corpora

Scenario's onder scenarios/upstream/ zijn geïmporteerd uit de testsuites van andere implementaties: de eigen testsuite van git (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7) en dulwich (6). De fixture-trees die ze nodig hebben, zijn opgenomen onder fixtures/upstream/, zodat het volledige corpus kan worden uitgevoerd vanuit een nieuwe checkout zonder netwerktoegang of lokale bestandspaden. Setup-scripts vinden ze via de omgevingsvariabele PITMASTER_ROOT.

composer verify:drift (bin/audit-upstream-drift) controleert of elk opgenomen upstream-geval aan een scenario is gekoppeld.

Supportmatrix

SUPPORT_MATRIX.md in de repository vermeldt elke git-functie binnen de scope met een status:

Het bestand wordt gegenereerd door bin/support-matrix vanuit config/support-matrix.json. config/support-evidence.json koppelt elke rij van DONE en PART aan concrete tests en oracle-scenario's, en composer verify:evidence faalt als een rij geen bewijs heeft. CI genereert de matrix opnieuw en faalt als het vastgelegde bestand afwijkt.

Een rij met DONE betekent dat de vastgelegde scenario's ermee overeenkomen met git. Het gedrag kan buiten die scenario's nog steeds afwijken; bekende verschillen worden bijgehouden in de issue tracker.

Benchmarks

Voor prestatieverbeteringen wordt de harness onder bench/ gebruikt:

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 controleert het smoketestverslag aan de hand van de vastgelegde drempelwaarden.