# Testarea și oracle-ul git

Pitmaster folosește binarul canonic `git` ca oracle: dacă `git` acceptă ce scrie Pitmaster și Pitmaster citește ce scrie `git`, comportamentul este corect. Infrastructura de testare se află în depozitul Pitmaster. Pachetul Composer include doar `src/` și `bin/pitmaster`, așa că rulați tot ce urmează dintr-o clonă după `composer install`.

## Suite de teste

| Comandă | Ce rulează | Necesită `git` |
|---------|--------------|-------------|
| `composer test:unit` | PHPUnit `unit`: teste izolate ale componentelor | Nu |
| `composer test:integration` | PHPUnit `integration`: Pitmaster și `git` lucrează pe aceleași depozite | Da |
| `composer test:oracle` | `bin/test-regression`: fiecare scenariu oracle | Da |
| `composer test` | PHPUnit (ambele suite) plus testul de regresie oracle | Da |
| `./bin/verify-all` | `composer verify`: dovezi de compatibilitate, diferențe față de versiunile din amonte, artefact de probă, test rapid de mutații, `composer audit`, PHPStan, standarde de cod și `composer test` | Da |

CI rulează suita unitară pe mai multe versiuni PHP, suita de integrare, testul de regresie oracle (`PITMASTER_TEST_JOBS=4`) și verificările dovezilor de compatibilitate și ale diferențelor față de versiunile din amonte.

## Scenarii oracle

Fiecare scenariu este un director în `scenarios/<category>/` (761 în total, dintre care 156 create pentru Pitmaster și 605 importate din alte implementări Git):

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

`scenario.json` indică comanda de rulat cu `git` și comanda echivalentă Pitmaster, precum și ce trebuie să corespundă:

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

O rulare copiază depozitul creat de `setup.sh`, rulează oracle-ul și comenzile Pitmaster pe copii separate și compară ieșirile, obiectele, referințele și jurnalul. `fsck_clean` impune, de asemenea, ca `git fsck` să accepte depozitul scris de Pitmaster. Ieșirea oracle este capturată din `git` când lipsește sau este reîmprospătată; în caz contrar, sunt folosite fișierele `oracle/` comise.

Un scenariu acoperă exact cazurile create de configurarea sa. De exemplu, scenariile diff compară fișiere modificate, motiv pentru care diferențele de ieșire diff pentru fișiere noi, șterse și binare, listate în [Diff](https://pitmaster.inline0.dev/ro/docs/operations/diff), nu sunt detectate de acestea.

### Lucrul cu scenariile

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

Pentru a verifica mai multe versiuni git, listați-le în `PITMASTER_TEST_GIT_BINARIES` și rulați testul rapid:

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

## Corpusuri din amonte

Scenariile din `scenarios/upstream/` sunt importate din suitele de teste ale altor implementări: suita proprie de teste a git (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7) și dulwich (6). Arborii cu datele de test necesari sunt incluși în `fixtures/upstream/`, astfel încât întregul corpus poate fi rulat după o clonare nouă, fără acces la rețea sau căi locale ale mașinii. Scripturile de configurare îi găsesc prin variabila de mediu `PITMASTER_ROOT`.

`composer verify:drift` (`bin/audit-upstream-drift`) verifică dacă fiecare caz din amonte inclus este asociat unui scenariu.

## Matricea de compatibilitate

`SUPPORT_MATRIX.md` din depozit listează fiecare funcție git inclusă în domeniul de aplicare, împreună cu starea sa:

| Stare | Semnificație |
|--------|---------|
| `DONE` | Implementată și verificată cu oracle-ul în limitele de compatibilitate declarate |
| `PART` | Implementată parțial |
| `TODO` | Inclusă în domeniul de aplicare, dar încă neimplementată |
| `DEFER` | Nu este încă planificată |
| `N/A` | În afara domeniului de aplicare |

Fișierul este generat de `bin/support-matrix` din `config/support-matrix.json`. `config/support-evidence.json` leagă fiecare rând `DONE` și `PART` de teste concrete și scenarii oracle, iar `composer verify:evidence` eșuează dacă un rând nu are dovezi. CI regenerează matricea și eșuează dacă fișierul comis diferă.

Un rând `DONE` înseamnă că scenariile înregistrate pentru acesta corespund cu git. Comportamentul poate diferi în continuare în afara acestor scenarii; diferențele cunoscute sunt urmărite în [trackerul de probleme](https://github.com/inline0/pitmaster/issues).

## Teste de performanță

Activitățile de optimizare a performanței folosesc instrumentul de testare din `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 verifică raportul testului rapid în raport cu pragurile comise.