# Testovanie a oracle nástroja git

Pitmaster považuje kanonický binárny súbor `git` za oracle: ak `git` prijme to, čo Pitmaster zapíše, a Pitmaster načíta to, čo `git` zapíše, správanie je správne. Infraštruktúra testov sa nachádza v repozitári Pitmaster. Balík Composer obsahuje iba `src/` a `bin/pitmaster`, preto všetko uvedené nižšie spúšťajte z klonu po `composer install`.

## Testovacie sady

| Príkaz | Čo spúšťa | Vyžaduje `git` |
|---------|--------------|-------------|
| `composer test:unit` | sada PHPUnit `unit`: izolované testy komponentov | Nie |
| `composer test:integration` | sada PHPUnit `integration`: Pitmaster a `git` pracujúce s rovnakými repozitármi | Áno |
| `composer test:oracle` | `bin/test-regression`: všetky scenáre oracle | Áno |
| `composer test` | PHPUnit (obe sady) a regresné testy oracle | Áno |
| `./bin/verify-all` | `composer verify`: dôkazy o podpore, odchýlky od upstreamu, artefakt dôkazu, smoke test mutácií, `composer audit`, PHPStan, štandardy kódovania a `composer test` | Áno |

CI spúšťa jednotkovú sadu na viacerých verziách PHP, integračnú sadu, regresné testy oracle (`PITMASTER_TEST_JOBS=4`) a kontroly dôkazov o podpore a odchýlok od upstreamu.

## Scenáre oracle

Každý scenár je adresárom v `scenarios/<category>/` (spolu ich je 761: 156 bolo vytvorených pre Pitmaster a 605 importovaných z iných implementácií Git):

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

`scenario.json` uvádza príkaz, ktorý sa má spustiť pomocou `git`, jeho ekvivalentný príkaz Pitmaster a požiadavky na zhodu:

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

Spustenie skopíruje repozitár vytvorený pomocou `setup.sh`, spustí referenčnú implementáciu a príkazy Pitmaster v samostatných kópiách a porovná výstupy, objekty, odkazy a záznam. `fsck_clean` tiež vyžaduje, aby `git fsck` dokázal spracovať repozitár vytvorený pomocou Pitmaster. Výstup referenčnej implementácie sa zachytí z `git`, ak chýba alebo sa obnovuje; inak sa použijú potvrdené súbory `oracle/`.

Scenár pokrýva presne tie prípady, ktoré pripraví jeho nastavenie. Napríklad scenáre diff porovnávajú upravené súbory, preto v nich nie sú zachytené rozdiely vo výstupe diff pre nové, odstránené a binárne súbory uvedené v [Diff](https://pitmaster.inline0.dev/sk/docs/operations/diff).

### Práca so scenármi

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

Ak chcete skontrolovať niekoľko verzií git, uveďte ich v `PITMASTER_TEST_GIT_BINARIES` a spustite smoke test:

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

## Korpusy z upstreamu

Scenáre v `scenarios/upstream/` sa importujú z testovacích sád iných implementácií: vlastná testovacia sada nástroja git (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7) a dulwich (6). Potrebné stromy testovacích súborov sú uložené v `fixtures/upstream/`, takže celý korpus možno spustiť z čerstvého checkoutu bez prístupu k sieti a ciest lokálnych pre konkrétny počítač. Nastavovacie skripty ich nájdu pomocou premennej prostredia `PITMASTER_ROOT`.

`composer verify:drift` (`bin/audit-upstream-drift`) kontroluje, či je každý uložený upstreamový prípad priradený k scenáru.

## Matica podpory

`SUPPORT_MATRIX.md` v repozitári uvádza všetky funkcie git v rozsahu spolu s ich stavom:

| Stav | Význam |
|--------|---------|
| `DONE` | Implementované a overené pomocou oracle v rámci deklarovaného rozsahu zhody |
| `PART` | Čiastočne implementované |
| `TODO` | V rozsahu, zatiaľ neimplementované |
| `DEFER` | Zatiaľ sa neplánuje |
| `N/A` | Mimo rozsahu |

Súbor generuje `bin/support-matrix` z `config/support-matrix.json`. `config/support-evidence.json` prepája každý riadok `DONE` a `PART` s konkrétnymi testami a scenármi oracle a `composer verify:evidence` zlyhá, ak riadok nemá žiadny dôkaz. CI maticu znova vygeneruje a zlyhá, ak sa vygenerovaný súbor líši od potvrdeného súboru.

Riadok `DONE` znamená, že zaznamenané scenáre sa zhodujú s git. Správanie sa môže líšiť mimo týchto scenárov; známe rozdiely sa sledujú v [sledovači problémov](https://github.com/inline0/pitmaster/issues).

## Výkonnostné testy

Práca na výkonnosti využíva testovací rámec v `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 overuje smoke report podľa potvrdených prahových hodnôt.