# Δοκιμές

Το Greph επικυρώνεται με τρία επίπεδα δοκιμών:

1. **Δοκιμές μονάδων** για μεμονωμένα στοιχεία (αναλυτές, διασχίσεις, κωδικοποιητές, επιλογές).
2. **Σύνολο παλινδρόμησης oracle** που συγκρίνει τη μοναδική έξοδο του Greph με τα κανονικά δυαδικά αρχεία `grep`, `ripgrep` και `ast-grep` σε ένα σταθερό σύνολο σεναρίων.
3. **Πίνακας δυνατοτήτων με βάση ελέγχους** που επιβεβαιώνει τις επαληθευμένες δυνατότητες των περιβλημάτων `rg` και `sg`.

Το CI εκτελείται σε κάθε push στο `main` και σε κάθε αίτημα έλξης (`.github/workflows/ci.yml`). Εκτελεί ελέγχους προτύπων κώδικα (`composer cs`), στατική ανάλυση (`composer analyse`), τις σουίτες δοκιμών μονάδων και ενσωμάτωσης του PHPUnit (`composer test`) και το `composer audit` στο PHP 8.4. Το σύνολο oracle (`composer test:oracle`) δεν αποτελεί μέρος του CI, ενώ ο πίνακας δυνατοτήτων αναδημιουργείται χειροκίνητα με το `php bin/feature-matrix`. Η σουίτα PHPUnit περιέχει μια δοκιμή που δημιουργεί τον πίνακα με τα εργαλεία upstream `rg` και `sg` δηλωμένα ως μη διαθέσιμα και ελέγχει τη δομή της αναφοράς, ώστε να μην αποτυγχάνει όταν παλινδρομεί ένας μεμονωμένος έλεγχος.

## Εργασία από κλώνο

Όλα όσα περιλαμβάνει αυτή η σελίδα απαιτούν κλώνο του αποθετηρίου. Επειδή το πακέτο Composer 0.2.3 περιέχει μόνο το `src/` και τα τέσσερα εκτελέσιμα χρόνου εκτέλεσης, τα `tests/`, `scenarios/`, `benchmarks/` και τα σενάρια ανάπτυξης στο `bin/` δεν περιλαμβάνονται σε αυτό.

```bash
git clone https://github.com/inline0/greph
cd greph
composer install
```

## Εκτέλεση των δοκιμών

```bash
# PHPUnit unit and integration suites
composer test

# Oracle regression corpus
composer test:oracle

# Static analysis
composer analyse

# Coding standards
composer cs
composer cs:fix

# Full release-grade verification (analyse + cs + test + test:oracle)
composer verify
```

Το `composer verify` είναι απαραίτητη προϋπόθεση για κάθε έκδοση. Αν αποτύχει, η αλλαγή δεν είναι ολοκληρωμένη.

## Το μοντέλο oracle

Το Greph ακολουθεί ένα μοντέλο επαλήθευσης με βάση oracle. Για κάθε σενάριο εκτελούνται τρεις εντολές:

1. **Oracle**: `grep`, `ripgrep` ή `ast-grep`, με έξοδο καταγεγραμμένη για το σύνολο σεναρίων.
2. **Πραγματικό αποτέλεσμα**: Greph, με έξοδο καταγεγραμμένη για το ίδιο σύνολο.
3. **Συγκριτής**: δομημένη σύγκριση που ελέγχει ισοδυναμία γραμμή προς γραμμή ή σημασιολογικά.

Αν το Greph διαφωνεί με το oracle, το Greph είναι λανθασμένο. Αν τα `grep` και `rg` διαφωνούν μεταξύ τους, το σενάριο καταγράφει τη διαφωνία στο `oracle_disagreement`, κατονομάζει το εργαλείο που ακολουθεί το Greph στο `greph_follows` και ορίζει τη σύγκριση με το άλλο εργαλείο ως `skip`. Στο σύνολο υπάρχουν και οι δύο κατευθύνσεις.

Τα σενάρια κειμένου συγκρίνονται με τα `grep` και `rg`, ενώ τα σενάρια AST και επανεγγραφής με το `sg`. Η έξοδος oracle καταγράφεται μία φορά και δεσμεύεται στον φάκελο `oracle/` κάθε σεναρίου, επομένως μια συνηθισμένη εκτέλεση χρειάζεται μόνο το PHP· τα εξωτερικά εργαλεία χρειάζονται μόνο για την καταγραφή ή ανανέωση της εξόδου oracle.

Η υλοποίηση βρίσκεται στο `tests/Oracle/` και τα σενάρια βρίσκονται στα `scenarios/text/`, `scenarios/ast/`, `scenarios/rewrite/` και `scenarios/edge/`.

## Διάταξη σεναρίου

Κάθε σενάριο είναι ένας αυτοτελής φάκελος:

```
scenarios/text/literal-simple/
├── scenario.json     # name, category, pattern, flags, path
├── setup/            # corpus to search through
├── oracle/           # captured oracle output (grep.txt, rg.txt, rg.json, ...)
├── actual/           # captured greph output (generated, git-ignored)
└── reports/          # comparison results (generated, git-ignored)
```

Το `scenario.json` δηλώνει το μοτίβο, τις σημαίες και τη διαδρομή αναζήτησης. Ένα προαιρετικό αντικείμενο `expectations` ορίζει τη λειτουργία σύγκρισης ανά oracle (`exact`, `semantic` ή `skip`)· χωρίς αυτό, τα σενάρια κειμένου συγκρίνουν ακριβώς τα `grep` και `rg` και σημασιολογικά το `rg` JSON, ενώ τα σενάρια AST και επανεγγραφής συγκρίνονται με το `sg`.

## Εκτέλεση ενός σεναρίου

Το αποθετήριο διαθέτει ένα μικρό σύνολο CLI για εργασία με μεμονωμένα σενάρια. Είναι εργαλεία ανάπτυξης, όχι σημεία εισόδου χρόνου εκτέλεσης: βρίσκονται δίπλα στα εκτελέσιμα χρόνου εκτέλεσης στο `bin/`, αλλά δεν αποτελούν μέρος του πακέτου Composer. Καθένα δέχεται το όνομα του σεναρίου σε σχέση με το `scenarios/`.

```bash
# Capture oracle output for a scenario (needs grep and rg, or sg)
./bin/oracle text/literal-simple

# Run greph against a scenario, capture its output
./bin/actual text/literal-simple

# Diff oracle vs actual
./bin/compare text/literal-simple

# Full pipeline: oracle (only if missing) -> actual -> compare
./bin/test-scenario text/literal-simple

# Recapture the oracle output first
./bin/test-scenario text/literal-simple --refresh
```

## Εκτέλεση της πλήρους σουίτας παλινδρόμησης

```bash
# All scenarios (the same as composer test:oracle)
./bin/test-regression

# Filter by category
./bin/test-regression --category text
./bin/test-regression --category ast
./bin/test-regression --category rewrite
./bin/test-regression --category edge

# Print only failures and the summary
./bin/test-regression --fast

# Recapture every oracle before comparing
./bin/test-regression --refresh
```

Τα σενάρια εκτελούνται πάντα ένα κάθε φορά. Το `--jobs N` γίνεται δεκτό και εμφανίζεται στη γραμμή σύνοψης, αλλά δεν εκτελεί τίποτα παράλληλα ([#7](https://github.com/inline0/greph/issues/7)). Σε έναν νέο κλώνο, τα `text/no-ignore` και `text/explicit-file-input` αποτυγχάνουν, επειδή τα αρχεία δεδομένων δοκιμών τους στο `setup/vendor/` δεν έχουν δεσμευτεί ([#6](https://github.com/inline0/greph/issues/6)).

Η σουίτα παλινδρόμησης είναι η πύλη για νέες συμπεριφορές. Μια νέα σημαία, μια νέα οριακή περίπτωση ή μια διόρθωση σφάλματος απαιτεί ένα σενάριο που καταγράφει την αναμενόμενη συμπεριφορά με βάση oracle.

## Αναφορά συμμόρφωσης

```bash
./bin/verify-compliance
```

Το `verify-compliance` δεν εκτελεί τίποτα από μόνο του. Διαβάζει τα αρχεία oracle, αποτελεσμάτων και αναφοράς που άφησε πίσω της η τελευταία εκτέλεση σεναρίου και εμφανίζει ποια σενάρια περνούν, ποια αποτυγχάνουν και ποια δεν έχουν ακόμη αναφορά. Εκτελέστε πρώτα το `./bin/test-regression`. Το `--output report.json` γράφει επίσης την αναφορά ως JSON. Αυτή είναι η κατάλληλη εντολή όταν θέλετε να μάθετε «είναι έτοιμος για έκδοση ο τρέχων κλάδος;».

## Ροή ανάπτυξης με δοκιμές πρώτα

Κατά την προσθήκη μιας δυνατότητας:

1. Γράψτε έναν φάκελο σεναρίου με το σύνολο δεδομένων και τις σημαίες που ασκούν τη νέα συμπεριφορά.
2. Εκτελέστε το `./bin/oracle <scenario>` για να καταγράψετε την έξοδο του κανονικού εργαλείου.
3. Υλοποιήστε τη δυνατότητα στο `src/`.
4. Εκτελέστε το `./bin/test-scenario <scenario>` για να επαληθεύσετε ότι το Greph συμφωνεί με το oracle.
5. Εκτελέστε το `./bin/test-regression --fast` για να βεβαιωθείτε ότι δεν παλινδρόμησε κάτι άλλο.
6. Εκτελέστε το `composer verify` πριν από τη δέσμευση.

Κατά τη διόρθωση ενός σφάλματος:

1. Καταγράψτε την αποτυχημένη είσοδο ως σενάριο.
2. Επιβεβαιώστε ότι το oracle παράγει την αναμενόμενη έξοδο.
3. Επιβεβαιώστε ότι το Greph δεν την παράγει.
4. Διορθώστε το σφάλμα.
5. Επιβεβαιώστε ότι το Greph συμφωνεί πλέον με το oracle.
6. Εκτελέστε το `composer verify`.

Το σενάριο παραμένει μόνιμα στο σύνολο, ώστε το σφάλμα να μην μπορεί να επανεμφανιστεί χωρίς να αποτύχουν το `composer test:oracle` (και το `composer verify`).