# Testování a Oracle git

Pitmaster považuje kanonickou binárku `git` za svůj Oracle: pokud `git` přijme to, co zapíše Pitmaster, a Pitmaster přečte to, co zapíše `git`, chování je správné. Testovací infrastruktura se nachází v repozitáři Pitmaster. Balíček Composer obsahuje pouze `src/` a `bin/pitmaster`, proto vše níže spouštějte z klonu po `composer install`.

## Testovací sady

| Příkaz | Co spouští | Vyžaduje `git` |
|---------|--------------|-------------|
| `composer test:unit` | Sada PHPUnit `unit`: izolované testy komponent | Ne |
| `composer test:integration` | Sada PHPUnit `integration`: Pitmaster a `git` pracují ve stejných repozitářích | Ano |
| `composer test:oracle` | `bin/test-regression`: všechny scénáře Oracle | Ano |
| `composer test` | PHPUnit (obě sady) a regresní test Oracle | Ano |
| `./bin/verify-all` | `composer verify`: důkazy podpory, odchylky od upstreamu, artefakt důkazu, kontrola mutací, `composer audit`, PHPStan, standardy kódování a `composer test` | Ano |

CI spouští jednotkovou sadu v několika verzích PHP, integrační sadu, regresní test Oracle (`PITMASTER_TEST_JOBS=4`) a kontroly důkazů podpory a odchylek od upstreamu.

## Scénáře Oracle

Každý scénář je adresář pod `scenarios/<category>/` (celkem 761, z toho 156 vytvořených pro Pitmaster a 605 převzatých z jiných implementací 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ádí příkaz ke spuštění pomocí `git` a odpovídající příkaz Pitmaster i to, co se musí shodovat:

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

Při běhu se zkopíruje repozitář vytvořený pomocí `setup.sh`, Oracle a příkazy Pitmaster se spustí v oddělených kopiích a porovnají se výstupy, objekty, reference a protokol. `fsck_clean` navíc vyžaduje, aby `git fsck` přijalo repozitář zapsaný pomocí Pitmaster. Výstup Oracle se při jeho chybějícím nebo obnoveném stavu zachytí z `git`; jinak se použijí potvrzené soubory `oracle/`.

Scénář pokrývá přesně případy, které vytvoří jeho nastavení. Scénáře diff například porovnávají upravené soubory, proto v nich nejsou zachyceny rozdíly ve výstupu diff pro nové, smazané a binární soubory uvedené v [Diff](https://pitmaster.inline0.dev/cs/docs/operations/diff).

### Práce se scénáři

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

Chcete-li ověřit několik verzí git, uveďte je v `PITMASTER_TEST_GIT_BINARIES` a spusťte smoke test:

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

## Upstream korpusy

Scénáře pod `scenarios/upstream/` jsou převzaty z testovacích sad jiných implementací: vlastní testovací sada git (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7) a dulwich (6). Potřebné stromy přípravků jsou součástí repozitáře pod `fixtures/upstream/`, takže celý korpus lze spustit z čerstvého checkoutu bez přístupu k síti nebo cest specifických pro daný počítač. Skripty nastavení je najdou pomocí proměnné prostředí `PITMASTER_ROOT`.

`composer verify:drift` (`bin/audit-upstream-drift`) kontroluje, zda je každý převzatý upstream případ přiřazen ke scénáři.

## Matice podpory

Soubor `SUPPORT_MATRIX.md` v repozitáři uvádí všechny podporované funkce git a jejich stav:

| Stav | Význam |
|--------|---------|
| `DONE` | Implementováno a ověřeno pomocí Oracle v rámci deklarovaného rozsahu shody |
| `PART` | Částečně implementováno |
| `TODO` | V rozsahu, zatím neimplementováno |
| `DEFER` | Zatím se neplánuje |
| `N/A` | Mimo rozsah |

Soubor generuje `bin/support-matrix` z `config/support-matrix.json`. `config/support-evidence.json` propojuje každý řádek `DONE` a `PART` s konkrétními testy a scénáři Oracle a `composer verify:evidence` selže, pokud řádek nemá žádný důkaz. CI matici znovu vygeneruje a při odlišném obsahu od potvrzeného souboru selže.

Řádek `DONE` znamená, že zaznamenané scénáře odpovídají git. Chování mimo tyto scénáře se může stále lišit; známé rozdíly jsou sledovány ve [sledování problémů](https://github.com/inline0/pitmaster/issues).

## Výkonnostní testy

Práce na výkonu využívá testovací nástroj pod `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 ověřuje výsledek smoke testu oproti potvrzeným limitům.