# Pengujian dan Oracle git

Pitmaster menjadikan biner `git` kanonis sebagai oracle: jika `git` menerima hasil yang ditulis Pitmaster, dan Pitmaster membaca hasil yang ditulis `git`, perilakunya benar. Infrastruktur pengujian berada di repositori Pitmaster. Paket Composer hanya menyertakan `src/` dan `bin/pitmaster`, jadi jalankan semua perintah di bawah ini dari hasil kloning setelah `composer install`.

## Rangkaian pengujian

| Perintah | Yang dijalankan | Memerlukan `git` |
|---------|--------------|-------------|
| `composer test:unit` | Rangkaian PHPUnit `unit`: tes komponen terisolasi | Tidak |
| `composer test:integration` | Rangkaian PHPUnit `integration`: Pitmaster dan `git` bekerja pada repositori yang sama | Ya |
| `composer test:oracle` | `bin/test-regression`: setiap skenario oracle | Ya |
| `composer test` | PHPUnit (kedua rangkaian) ditambah regresi oracle | Ya |
| `./bin/verify-all` | `composer verify`: bukti dukungan, perubahan upstream, artefak pembuktian, uji singkat mutasi, `composer audit`, PHPStan, standar penulisan kode, dan `composer test` | Ya |

CI menjalankan rangkaian unit pada beberapa versi PHP, rangkaian integrasi, regresi oracle (`PITMASTER_TEST_JOBS=4`), serta pemeriksaan bukti dukungan dan perubahan upstream.

## Skenario oracle

Setiap skenario berupa direktori di bawah `scenarios/<category>/` (total 761, 156 ditulis untuk Pitmaster dan 605 diimpor dari implementasi Git lainnya):

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

`scenario.json` mencantumkan perintah yang dijalankan dengan `git` beserta perintah Pitmaster yang setara, serta hal yang harus cocok:

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

Satu proses menjalankan perintah dengan menyalin repositori yang dibuat oleh `setup.sh`, menjalankan oracle dan perintah Pitmaster pada salinan terpisah, lalu membandingkan keluaran, objek, referensi, dan log. `fsck_clean` juga mengharuskan `git fsck` menerima repositori yang ditulis Pitmaster. Keluaran oracle diambil dari `git` jika belum tersedia atau diperbarui; jika tidak, digunakan berkas `oracle/` yang sudah di-commit.

Sebuah skenario hanya mencakup kasus yang dibuat oleh penyiapannya. Misalnya, skenario diff membandingkan berkas yang dimodifikasi; karena itu, perbedaan keluaran diff untuk berkas baru, terhapus, dan biner yang tercantum dalam [Diff](https://pitmaster.inline0.dev/id/docs/operations/diff) tidak terdeteksi oleh skenario tersebut.

### Bekerja dengan skenario

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

Untuk memeriksa beberapa versi git, cantumkan versinya di `PITMASTER_TEST_GIT_BINARIES` lalu jalankan uji singkat:

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

## Korpus upstream

Skenario di bawah `scenarios/upstream/` diimpor dari rangkaian pengujian implementasi lain: rangkaian pengujian git sendiri (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7), dan dulwich (6). Pohon fixture yang diperlukan tersedia di bawah `fixtures/upstream/`, sehingga seluruh korpus dapat dijalankan dari checkout baru tanpa akses jaringan atau jalur khusus mesin. Skrip penyiapan menemukannya melalui variabel lingkungan `PITMASTER_ROOT`.

`composer verify:drift` (`bin/audit-upstream-drift`) memeriksa apakah setiap kasus upstream yang disertakan dipetakan ke sebuah skenario.

## Matriks dukungan

`SUPPORT_MATRIX.md` di repositori mencantumkan semua fitur git yang termasuk dalam cakupan beserta statusnya:

| Status | Arti |
|--------|---------|
| `DONE` | Diimplementasikan dan diverifikasi dengan oracle dalam cakupan paritas yang dinyatakan |
| `PART` | Diimplementasikan sebagian |
| `TODO` | Termasuk dalam cakupan, belum diimplementasikan |
| `DEFER` | Belum direncanakan |
| `N/A` | Di luar cakupan |

Berkas ini dibuat oleh `bin/support-matrix` dari `config/support-matrix.json`. `config/support-evidence.json` menautkan setiap baris `DONE` dan `PART` ke pengujian dan skenario oracle yang konkret, sedangkan `composer verify:evidence` gagal jika ada baris tanpa bukti. CI membuat ulang matriks dan gagal jika berkas yang di-commit berbeda.

Baris `DONE` berarti skenario yang tercatat untuk baris tersebut cocok dengan git. Perilaku di luar skenario itu masih dapat berbeda; perbedaan yang diketahui dicatat di [pelacak masalah](https://github.com/inline0/pitmaster/issues).

## Tolok ukur

Pekerjaan performa menggunakan harness di bawah `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 memverifikasi laporan uji singkat terhadap ambang batas yang di-commit.