# Testēšana un git Oracle

Pitmaster par orākulu izmanto kanonisko `git` bināro failu: ja `git` pieņem to, ko raksta Pitmaster, un Pitmaster nolasa to, ko raksta `git`, uzvedība ir pareiza. Testēšanas infrastruktūra atrodas repozitorijā Pitmaster. Pakotnē Composer ir iekļautas tikai `src/` un `bin/pitmaster`, tāpēc, lai palaistu tālāk aprakstītos testus, vispirms klonējiet repozitoriju un izpildiet `composer install`.

## Testu kopas

| Komanda | Ko tā palaiž | Nepieciešams `git` |
|---------|--------------|-------------|
| `composer test:unit` | PHPUnit `unit` kopa: izolēti komponentu testi | Nē |
| `composer test:integration` | PHPUnit `integration` kopa: Pitmaster un `git` darbojas tajos pašos repozitorijos | Jā |
| `composer test:oracle` | `bin/test-regression`: visi orākula scenāriji | Jā |
| `composer test` | PHPUnit (abas kopas) un orākula regresijas testu | Jā |
| `./bin/verify-all` | `composer verify`: atbalsta pierādījumi, augšupstraumes izmaiņas, pierādījuma artefakts, mutāciju dūmu tests, `composer audit`, PHPStan, kodēšanas standarti un `composer test` | Jā |

CI palaiž vienību testu kopu ar vairākām PHP versijām, integrācijas testu kopu, orākula regresijas testu (`PITMASTER_TEST_JOBS=4`), kā arī atbalsta pierādījumu un augšupstraumes izmaiņu pārbaudes.

## Orākula scenāriji

Katrs scenārijs ir direktorijs zem `scenarios/<category>/` (kopā 761: 156 rakstīti Pitmaster un 605 importēti no citām Git implementācijām):

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

`scenario.json` norāda palaižamo komandu ar `git` un tai līdzvērtīgo Pitmaster komandu, kā arī to, kam jāsakrīt:

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

Palaišanas laikā tiek kopēts repozitorijs, ko izveidoja `setup.sh`, tad orākula komandas un Pitmaster komandas tiek izpildītas atsevišķās kopijās un salīdzinātas izvades, objekti, atsauces un žurnāls. `fsck_clean` papildus pieprasa, lai `git fsck` pieņemtu repozitoriju, ko izveidoja Pitmaster. Orākula izvade tiek iegūta no `git`, ja tās trūkst vai tā jāatjauno; citādi tiek izmantoti repozitorijā iekļautie `oracle/` faili.

Scenārijs aptver tikai tos gadījumus, ko izveido tā iestatīšana. Piemēram, diff scenāriji salīdzina modificētus failus, tāpēc tie neuztver atšķirības diff izvadē jaunajiem, dzēstajiem un binārajiem failiem, kas uzskaitītas [Diff](https://pitmaster.inline0.dev/lv/docs/operations/diff).

### Darbs ar scenārijiem

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

Lai pārbaudītu vairākas git versijas, norādiet tās failā `PITMASTER_TEST_GIT_BINARIES` un palaidiet dūmu testu:

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

## Augšupstraumes testu korpusi

Scenāriji, kas atrodas `scenarios/upstream/`, ir importēti no citu implementāciju testu kopām: paša git testu kopa (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7) un dulwich (6). Nepieciešamie testa datu koki ir iekļauti `fixtures/upstream/`, tāpēc visu korpusu var palaist pēc tīras repozitorija lejupielādes bez tīkla piekļuves vai lokāliem ceļiem. Iestatīšanas skripti tos atrod, izmantojot vides mainīgo `PITMASTER_ROOT`.

`composer verify:drift` (`bin/audit-upstream-drift`) pārbauda, vai katram iekļautajam augšupstraumes gadījumam ir atbilstošs scenārijs.

## Atbalsta matrica

`SUPPORT_MATRIX.md` repozitorijā uzskaita visas tvērumā ietvertās git funkcijas un to statusu:

| Statuss | Nozīme |
|--------|---------|
| `DONE` | Ieviests un pārbaudīts ar orākulu deklarētajā saderības tvērumā |
| `PART` | Ieviests daļēji |
| `TODO` | Iekļauts tvērumā, vēl nav ieviests |
| `DEFER` | Pagaidām nav plānots |
| `N/A` | Ārpus tvēruma |

Failu ģenerē `bin/support-matrix` no `config/support-matrix.json`. `config/support-evidence.json` sasaista katru `DONE` un `PART` rindu ar konkrētiem testiem un orākula scenārijiem, bet `composer verify:evidence` neizdodas, ja rindai nav pierādījumu. CI atjauno matricu un ziņo par kļūdu, ja tā atšķiras no repozitorijā esošā faila.

Rinda `DONE` nozīmē, ka tajā norādītie scenāriji atbilst git. Ārpus šiem scenārijiem uzvedība joprojām var atšķirties; zināmās atšķirības tiek reģistrētas [problēmu izsekotājā](https://github.com/inline0/pitmaster/issues).

## Veiktspējas testi

Veiktspējas uzlabojumiem tiek izmantots ietvars zem `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 pārbauda dūmu testa pārskatu, salīdzinot to ar repozitorijā iekļautajiem sliekšņiem.