# Testimine ja giti oraakel

Pitmaster kasutab kanoonilist `git` binaari oraaklina: kui `git` aktsepteerib seda, mida Pitmaster kirjutab, ja Pitmaster loeb seda, mida `git` kirjutab, on käitumine õige. Testitaristu asub hoidlas Pitmaster. Pakett Composer sisaldab ainult `src/` ja `bin/pitmaster`, seega käivita kõik allpool kirjeldatu kloonist pärast `composer install`.

## Testikogud

| Käsk | Käivitatavad testid | Vajab `git` |
|---------|--------------|-------------|
| `composer test:unit` | PHPUnit `unit` testikogu: eraldatud komponenditestid | Ei |
| `composer test:integration` | PHPUnit `integration` testikogu: Pitmaster ja `git` töötavad samades hoidlates | Jah |
| `composer test:oracle` | `bin/test-regression`: kõik oraakli stsenaariumid | Jah |
| `composer test` | PHPUnit (mõlemad testikogud) ja oraakli regressioonitest | Jah |
| `./bin/verify-all` | `composer verify`: tõendid toe kohta, ülesvoolu muudatused, tõestusartefakt, mutatsioonide suitsutest, `composer audit`, PHPStan, kodeerimisstandardid ja `composer test` | Jah |

CI käivitab üksustestid mitme PHP versiooniga, integratsioonitestid, oraakli regressioonitesti (`PITMASTER_TEST_JOBS=4`) ning toe tõendite ja ülesvoolu muudatuste kontrollid.

## Oraakli stsenaariumid

Iga stsenaarium on kataloog asukohas `scenarios/<category>/` (kokku 761, neist 156 loodud Pitmaster jaoks ja 605 imporditud teistest Git teostustest):

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

`scenario.json` määrab käivitatava käsu koos `git`-ga ja samaväärse Pitmaster käsu ning selle, mis peab kattuma:

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

Käivitamisel kopeeritakse hoidla, mille koostas `setup.sh`, käivitatakse oraakel ja käsud Pitmaster eraldi koopiates ning võrreldakse väljundeid, objekte, viiteid ja logi. `fsck_clean` nõuab lisaks, et `git fsck` aktsepteeriks hoidla, mille kirjutas Pitmaster. Oraakli väljund võetakse kohast `git`, kui see puudub või seda värskendatakse; muul juhul kasutatakse commit'itud `oracle/` faile.

Stsenaarium katab täpselt need juhud, mille selle seadistus loob. Näiteks diff-stsenaariumid võrdlevad muudetud faile, mistõttu [Diff](https://pitmaster.inline0.dev/et/docs/operations/diff) loetletud uute, kustutatud ja binaarfailide diff-väljundi erinevused jäävad neil märkamata.

### Stsenaariumidega töötamine

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

Mitme giti versiooni kontrollimiseks loetle need asukohas `PITMASTER_TEST_GIT_BINARIES` ja käivita suitsutest:

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

## Ülesvoolu testikogud

Asukohas `scenarios/upstream/` olevad stsenaariumid on imporditud teiste teostuste testikogudest: giti enda testikogust (412), isomorphic-gitist (71), libgit2-st (63), go-gitist (46), JGit-st (7) ja dulwichist (6). Nende vajalikud testipuud on lisatud asukohta `fixtures/upstream/`, nii et kogu testikogu töötab värskest väljavõttest ilma võrguühenduse või kohalike masinate teedeta. Seadistusskriptid leiavad need keskkonnamuutuja `PITMASTER_ROOT` kaudu.

`composer verify:drift` (`bin/audit-upstream-drift`) kontrollib, et iga lisatud ülesvoolu juht vastaks stsenaariumile.

## Toe maatriks

Hoidlas olev `SUPPORT_MATRIX.md` loetleb kõik käsitletavad giti funktsioonid koos olekuga:

| Olek | Tähendus |
|--------|---------|
| `DONE` | Teostatud ja oraakliga kontrollitud määratletud ühilduvusulatuses |
| `PART` | Osaliselt teostatud |
| `TODO` | Ulatuses, kuid veel teostamata |
| `DEFER` | Pole veel kavandatud |
| `N/A` | Väljaspool ulatust |

Faili loob `bin/support-matrix` asukohast `config/support-matrix.json`. `config/support-evidence.json` seob iga `DONE` ja `PART` rea konkreetsete testide ja oraakli stsenaariumidega ning `composer verify:evidence` annab vea, kui real puuduvad tõendid. CI loob maatriksi uuesti ja annab vea, kui see erineb commit'itud failist.

Rida `DONE` tähendab, et selle jaoks kirja pandud stsenaariumid ühtivad gitiga. Väljaspool neid stsenaariume võib käitumine siiski erineda; teadaolevad erinevused on kirjas [probleemide jälgijas](https://github.com/inline0/pitmaster/issues).

## Jõudlustestid

Jõudluse parandamiseks kasutatakse komplekti asukohas `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 kontrollib suitsutesti aruannet commit'itud lävendite alusel.