# Testiranje in oracle za git

Pitmaster uporablja kanarni binarni program `git` kot oracle: če `git` sprejme tisto, kar zapiše Pitmaster, in Pitmaster prebere tisto, kar zapiše `git`, je delovanje pravilno. Testna infrastruktura je v repozitoriju Pitmaster. Paket Composer vsebuje samo `src/` in `bin/pitmaster`, zato vse spodaj zaženite iz klona po `composer install`.

## Testne zbirke

| Ukaz | Kaj zažene | Potrebuje `git` |
|---------|--------------|-------------|
| `composer test:unit` | Zbirka PHPUnit `unit`: izolirani testi komponent | Ne |
| `composer test:integration` | Zbirka PHPUnit `integration`: Pitmaster in `git` delujeta na istih repozitorijih | Da |
| `composer test:oracle` | `bin/test-regression`: vsi scenariji oracle | Da |
| `composer test` | PHPUnit (obe zbirki) in regresijski test oracle | Da |
| `./bin/verify-all` | `composer verify`: dokazi podpore, odstopanja od izvornega projekta, dokazni artefakt, preizkus mutacij, `composer audit`, PHPStan, standardi kodiranja in `composer test` | Da |

CI zažene enotno zbirko v več različicah PHP, integracijsko zbirko, regresijski test oracle (`PITMASTER_TEST_JOBS=4`) ter preverjanji dokazov podpore in odstopanj od izvornega projekta.

## Scenariji oracle

Vsak scenarij je imenik pod `scenarios/<category>/` (skupaj 761; 156 jih je bilo napisanih za Pitmaster, 605 pa uvoženih iz drugih implementacij Git):

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

`scenario.json` določa ukaz, ki ga je treba zagnati z `git`, enakovredni ukaz Pitmaster in kaj se mora ujemati:

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

Zagon kopira repozitorij, ki ga je ustvaril `setup.sh`, zažene oracle in ukaze Pitmaster v ločenih kopijah ter primerja izhode, objekte, sklice in dnevnik. `fsck_clean` zahteva tudi, da `git fsck` sprejme repozitorij, ki ga je zapisal Pitmaster. Izhod oracle se zajame iz `git`, če manjka ali ga je treba osvežiti; sicer se uporabijo potrjene datoteke `oracle/`.

Scenarij zajema natanko primere, ki jih pripravi njegova nastavitev. Scenariji diff na primer primerjajo spremenjene datoteke, zato ne zaznajo razlik v izhodu diff za nove, izbrisane in binarne datoteke, navedene v [Diff](https://pitmaster.inline0.dev/sl/docs/operations/diff).

### Delo s scenariji

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

Če želite preveriti več različic git, jih navedite v `PITMASTER_TEST_GIT_BINARIES` in zaženite preizkus delovanja:

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

## Izvorni korpusi

Scenariji pod `scenarios/upstream/` so uvoženi iz testnih zbirk drugih implementacij: lastna testna zbirka git (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7) in dulwich (6). Potrebna drevesa z vzorčnimi datotekami so vključena pod `fixtures/upstream/`, zato se celoten korpus zažene iz svežega prevzema brez omrežnega dostopa ali poti, vezanih na določen računalnik. Skripti za nastavitev jih poiščeta prek spremenljivke okolja `PITMASTER_ROOT`.

`composer verify:drift` (`bin/audit-upstream-drift`) preveri, ali je vsak vključeni primer izvornega projekta povezan s scenarijem.

## Matrika podpore

`SUPPORT_MATRIX.md` v repozitoriju navaja vse funkcije git znotraj obsega in njihovo stanje:

| Stanje | Pomen |
|--------|---------|
| `DONE` | Implementirano in preverjeno z oracle v opredeljenem obsegu paritete |
| `PART` | Delno implementirano |
| `TODO` | V obsegu, še ni implementirano |
| `DEFER` | Za zdaj ni načrtovano |
| `N/A` | Zunaj obsega |

Datoteko ustvari `bin/support-matrix` iz `config/support-matrix.json`. `config/support-evidence.json` poveže vsako vrstico `DONE` in `PART` s konkretnimi testi in scenariji oracle, `composer verify:evidence` pa odpove, če vrstica nima dokazov. CI znova ustvari matriko in odpove, če se razlikuje od potrjene datoteke.

Vrstica `DONE` pomeni, da se zanjo zabeleženi scenariji ujemajo z git. Delovanje zunaj teh scenarijev se lahko še vedno razlikuje; znane razlike so spremljane v [sledilniku težav](https://github.com/inline0/pitmaster/issues).

## Primerjalni testi

Optimizacija zmogljivosti uporablja preizkusno ogrodje 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 preverja poročilo preizkusa delovanja glede na potrjene pragove.