# 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

| Opdracht | Wat wordt uitgevoerd | `git` nodig |
|---------|-----------------------|---------------|
| `composer test:unit` | suite PHPUnit `unit`: geïsoleerde componenttests | Nee |
| `composer test:integration` | suite PHPUnit `integration`: Pitmaster en `git` werken op dezelfde repositories | Ja |
| `composer test:oracle` | `bin/test-regression`: elk oracle-scenario | Ja |
| `composer test` | PHPUnit (beide suites) plus de oracle-regressietest | Ja |
| `./bin/verify-all` | `composer verify`: ondersteuningsbewijs, upstream-afwijkingen, bewijsartefact, mutatie-smoketest, `composer audit`, PHPStan, codeerstijlen en `composer test` | Ja |

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:

```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 }
}
```

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](https://pitmaster.inline0.dev/nl/docs/operations/diff) staan, er niet door gedetecteerd.

### Werken met scenario's

```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
```

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

```bash
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:

| Status | Betekenis |
|--------|-----------|
| `DONE` | Geïmplementeerd en met oracle geverifieerd binnen de gedeclareerde pariteitsscope |
| `PART` | Gedeeltelijk geïmplementeerd |
| `TODO` | Binnen scope, nog niet geïmplementeerd |
| `DEFER` | Nog niet gepland |
| `N/A` | Buiten scope |

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](https://github.com/inline0/pitmaster/issues).

## Benchmarks

Voor prestatieverbeteringen wordt de harness onder `bench/` gebruikt:

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