# Testavimas ir git orakulas

Pitmaster kanoninį `git` dvejetainį failą laiko orakulu: jei `git` priima tai, ką įrašo Pitmaster, ir Pitmaster perskaito tai, ką įrašo `git`, veikimas teisingas. Testavimo infrastruktūra yra Pitmaster saugykloje. Composer pakete yra tik `src/` ir `bin/pitmaster`, todėl viską, kas aprašyta toliau, vykdykite iš klono po `composer install`.

## Testų rinkiniai

| Komanda | Ką vykdo | Reikia `git` |
|---------|--------------|-------------|
| `composer test:unit` | PHPUnit `unit` rinkinys: izoliuoti komponentų testai | Ne |
| `composer test:integration` | PHPUnit `integration` rinkinys: Pitmaster ir `git` darbas su tomis pačiomis saugyklomis | Taip |
| `composer test:oracle` | `bin/test-regression`: visi orakulo scenarijai | Taip |
| `composer test` | PHPUnit (abu rinkiniai) ir orakulo regresija | Taip |
| `./bin/verify-all` | `composer verify`: palaikymo įrodymai, aukštesniųjų projektų pokyčiai, įrodymo artefaktas, mutacijų patikra, `composer audit`, PHPStan, kodavimo standartai ir `composer test` | Taip |

CI vykdo vienetinių testų rinkinį su keliomis PHP versijomis, integracinių testų rinkinį, orakulo regresiją (`PITMASTER_TEST_JOBS=4`) ir palaikymo įrodymų bei aukštesniųjų projektų pokyčių patikras.

## Orakulo scenarijai

Kiekvienas scenarijus yra katalogas aplanke `scenarios/<category>/` (iš viso 761, 156 sukurtų Pitmaster, o 605 importuotų iš kitų Git realizacijų):

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

`scenario.json` nurodo komandą, kurią reikia vykdyti su `git`, jai lygiavertę Pitmaster komandą ir tai, kas turi sutapti:

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

Vykdymo metu nukopijuojama `setup.sh` sukurta saugykla, orakulas ir Pitmaster komandos paleidžiamos atskirose kopijose, o išvestys, objektai, nuorodos ir žurnalas palyginami. `fsck_clean` taip pat reikalauja, kad `git fsck` priimtų Pitmaster sukurtą saugyklą. Orakulo išvestis užfiksuojama iš `git`, jei jos nėra arba ji atnaujinama; kitu atveju naudojami įrašyti `oracle/` failai.

Scenarijus apima tiksliai tuos atvejus, kuriuos sukuria jo sąranka. Pavyzdžiui, diff scenarijuose lyginami pakeisti failai, todėl [Diff](https://pitmaster.inline0.dev/lt/docs/operations/diff) išvardyti naujų, ištrintų ir dvejetainių failų diff išvesties skirtumai jais neaptinkami.

### Darbas su scenarijais

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

Norėdami patikrinti kelias git versijas, išvardykite jas `PITMASTER_TEST_GIT_BINARIES` ir paleiskite greitąjį testą:

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

## Aukštesniųjų projektų testų rinkiniai

`scenarios/upstream/` scenarijai importuoti iš kitų realizacijų testų rinkinių: paties git testų rinkinio (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7) ir dulwich (6). Jiems reikalingi testinių duomenų medžiai įtraukti į saugyklą aplanke `fixtures/upstream/`, todėl visas rinkinys veikia iš naujo klono be tinklo prieigos ir vietinių kompiuterio kelių. Sąrankos scenarijai juos randa naudodami aplinkos kintamąjį `PITMASTER_ROOT`.

`composer verify:drift` (`bin/audit-upstream-drift`) tikrina, ar kiekvienas įtrauktas aukštesniojo projekto atvejis susietas su scenarijumi.

## Palaikymo matrica

`SUPPORT_MATRIX.md` saugykloje pateikia visas į aprėptį įtrauktas git funkcijas ir jų būseną:

| Būsena | Reikšmė |
|--------|---------|
| `DONE` | Įgyvendinta ir patikrinta orakulu pagal deklaruotą suderinamumo aprėptį |
| `PART` | Įgyvendinta iš dalies |
| `TODO` | Įtraukta į aprėptį, bet dar neįgyvendinta |
| `DEFER` | Kol kas neplanuojama |
| `N/A` | Už aprėpties ribų |

Failą iš `config/support-matrix.json` sugeneruoja `bin/support-matrix`. `config/support-evidence.json` susieja kiekvieną `DONE` ir `PART` eilutę su konkrečiais testais ir orakulo scenarijais, o `composer verify:evidence` nepavyksta, jei eilutė neturi įrodymų. CI iš naujo sugeneruoja matricą ir pateikia klaidą, jei ji skiriasi nuo įrašyto failo.

Eilutė `DONE` reiškia, kad joje nurodyti scenarijai sutampa su git. Už šių scenarijų ribų veikimas vis dar gali skirtis; žinomi skirtumai registruojami [issue tracker](https://github.com/inline0/pitmaster/issues).

## Našumo testai

Našumo darbams naudojama testavimo aplinka aplanke `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 patikrina greitojo testo ataskaitą pagal įrašytas ribines reikšmes.