# Δοκιμές και Oracle του git

Το Pitmaster θεωρεί το κανονικό δυαδικό αρχείο `git` ως oracle: αν το `git` αποδέχεται όσα γράφει το Pitmaster και το Pitmaster διαβάζει όσα γράφει το `git`, η συμπεριφορά είναι σωστή. Η υποδομή δοκιμών βρίσκεται στο αποθετήριο Pitmaster. Το πακέτο Composer περιλαμβάνει μόνο τα `src/` και `bin/pitmaster`, επομένως εκτελέστε όλα τα παρακάτω από έναν κλώνο μετά το `composer install`.

## Σουίτες δοκιμών

| Εντολή | Τι εκτελεί | Απαιτεί `git` |
|---------|--------------|-------------|
| `composer test:unit` | Σουίτα PHPUnit `unit`: απομονωμένες δοκιμές στοιχείων | Όχι |
| `composer test:integration` | Σουίτα PHPUnit `integration`: τα Pitmaster και `git` λειτουργούν στα ίδια αποθετήρια | Ναι |
| `composer test:oracle` | `bin/test-regression`: κάθε σενάριο oracle | Ναι |
| `composer test` | PHPUnit (και οι δύο σουίτες) μαζί με την παλινδρομική δοκιμή oracle | Ναι |
| `./bin/verify-all` | `composer verify`: τεκμήρια υποστήριξης, αποκλίσεις από upstream, τεκμήριο απόδειξης, δοκιμή μετάλλαξης, `composer audit`, PHPStan, πρότυπα κώδικα και `composer test` | Ναι |

Το CI εκτελεί τη σουίτα μονάδων σε διάφορες εκδόσεις PHP, τη σουίτα ενσωμάτωσης, την παλινδρομική δοκιμή oracle (`PITMASTER_TEST_JOBS=4`) και τους ελέγχους τεκμηρίων υποστήριξης και αποκλίσεων από upstream.

## Σενάρια oracle

Κάθε σενάριο είναι ένας κατάλογος κάτω από το `scenarios/<category>/` (761 συνολικά, 156 γραμμένα για το Pitmaster και 605 εισαγμένα από άλλες υλοποιήσεις Git):

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

Το `scenario.json` ορίζει την εντολή που θα εκτελεστεί με το `git` και την ισοδύναμη εντολή Pitmaster, καθώς και τι πρέπει να συμφωνεί:

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

Μια εκτέλεση αντιγράφει το αποθετήριο που δημιούργησε το `setup.sh`, εκτελεί το oracle και τις εντολές Pitmaster σε ξεχωριστά αντίγραφα και συγκρίνει εξόδους, αντικείμενα, refs και log. Το `fsck_clean` απαιτεί επίσης το `git fsck` να αποδέχεται το αποθετήριο που έγραψε το Pitmaster. Η έξοδος oracle καταγράφεται από το `git` όταν λείπει ή ανανεώνεται· διαφορετικά χρησιμοποιούνται τα δεσμευμένα αρχεία `oracle/`.

Ένα σενάριο καλύπτει ακριβώς τις περιπτώσεις που δημιουργεί η ρύθμισή του. Για παράδειγμα, τα σενάρια diff συγκρίνουν τροποποιημένα αρχεία, γι' αυτό δεν εντοπίζουν τις διαφορές εξόδου diff για νέα, διαγραμμένα και δυαδικά αρχεία που παρατίθενται στο [Diff](https://pitmaster.inline0.dev/el/docs/operations/diff).

### Εργασία με σενάρια

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

Για να ελέγξετε διάφορες εκδόσεις του git, καταχωρίστε τις στο `PITMASTER_TEST_GIT_BINARIES` και εκτελέστε τη δοκιμή smoke:

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

## Σώματα δοκιμών upstream

Τα σενάρια κάτω από το `scenarios/upstream/` έχουν εισαχθεί από τις σουίτες δοκιμών άλλων υλοποιήσεων: τη σουίτα δοκιμών του ίδιου του git (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7) και dulwich (6). Τα δέντρα fixture που χρειάζονται περιλαμβάνονται στο `fixtures/upstream/`, ώστε όλο το σώμα δοκιμών να εκτελείται από νέα ανάκτηση χωρίς πρόσβαση στο δίκτυο ή τοπικές διαδρομές μηχανήματος. Τα script ρύθμισης τα εντοπίζουν μέσω της μεταβλητής περιβάλλοντος `PITMASTER_ROOT`.

Το `composer verify:drift` (`bin/audit-upstream-drift`) ελέγχει ότι κάθε εισαγμένη υπόθεση upstream αντιστοιχίζεται σε σενάριο.

## Πίνακας υποστήριξης

Το `SUPPORT_MATRIX.md` στο αποθετήριο καταγράφει κάθε λειτουργία git εντός πεδίου, μαζί με την κατάστασή της:

| Κατάσταση | Σημασία |
|--------|---------|
| `DONE` | Υλοποιημένο και επαληθευμένο με oracle εντός του δηλωμένου πεδίου ισοτιμίας |
| `PART` | Εν μέρει υλοποιημένο |
| `TODO` | Εντός πεδίου, δεν έχει υλοποιηθεί ακόμη |
| `DEFER` | Δεν έχει προγραμματιστεί ακόμη |
| `N/A` | Εκτός πεδίου |

Το αρχείο δημιουργείται από το `bin/support-matrix` από το `config/support-matrix.json`. Το `config/support-evidence.json` συνδέει κάθε γραμμή `DONE` και `PART` με συγκεκριμένες δοκιμές και σενάρια oracle, ενώ το `composer verify:evidence` αποτυγχάνει όταν μια γραμμή δεν έχει τεκμήρια. Το CI αναδημιουργεί τον πίνακα και αποτυγχάνει αν το δεσμευμένο αρχείο διαφέρει.

Μια γραμμή `DONE` σημαίνει ότι τα σενάρια που έχουν καταγραφεί γι' αυτήν συμφωνούν με το git. Η συμπεριφορά εκτός αυτών των σεναρίων μπορεί να διαφέρει· οι γνωστές διαφορές καταγράφονται στο [σύστημα παρακολούθησης ζητημάτων](https://github.com/inline0/pitmaster/issues).

## Δοκιμές επιδόσεων

Οι εργασίες απόδοσης χρησιμοποιούν το πλαίσιο δοκιμών κάτω από το `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 επαληθεύει την αναφορά smoke έναντι των δεσμευμένων ορίων.