# Testovanie

Greph sa overuje v troch vrstvách testov:

1. **Jednotkové testy** izolovaných komponentov (parsery, prechádzače, kodeky, možnosti).
2. **Regresný korpus oracle**, ktorý porovnáva výstup Greph s kanonickými binárnymi súbormi `grep`, `ripgrep` a `ast-grep` na pevnej sade scenárov.
3. **Matica funkcií založená na sondách**, ktorá overuje dostupné funkcie obalov `rg` a `sg`.

CI sa spúšťa pri každom odoslaní zmien do `main` a pri každej požiadavke na zlúčenie (`.github/workflows/ci.yml`). Spúšťa kontrolu štandardov kódovania (`composer cs`), statickú analýzu (`composer analyse`), sady jednotkových a integračných testov PHPUnit (`composer test`) a `composer audit` na PHP 8.4. Korpus oracle (`composer test:oracle`) nie je súčasťou CI a matica funkcií sa znova generuje ručne pomocou `php bin/feature-matrix`. Sada PHPUnit obsahuje test, ktorý generuje maticu s nedostupnými nadväzujúcimi nástrojmi `rg` a `sg` a kontroluje tvar reportu, takže nezlyhá, keď sa pokazí jediná sonda.

## Práca s klonom

Všetko na tejto stránke vyžaduje klon repozitára. Keďže 0.2.3 balík Composer obsahuje iba `src/` a štyri spustiteľné súbory potrebné na beh; `tests/`, `scenarios/`, `benchmarks/` a vývojové skripty v `bin/` v ňom nie sú zahrnuté.

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

## Spustenie testov

```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` je podmienkou každého vydania. Ak neprejde, zmena nie je hotová.

## Model oracle

Greph používa model overovania riadený oracle. Pri každom scenári sa spustia tri príkazy:

1. **Oracle**: `grep`, `ripgrep` alebo `ast-grep`, ktorých výstup sa zachytí na korpuse scenárov.
2. **Skutočný výstup**: Greph, ktorého výstup sa zachytí na rovnakom korpuse.
3. **Porovnávač**: štruktúrovaný rozdiel, ktorý kontroluje zhodu po riadkoch alebo sémantickú zhodu.

Ak sa Greph nezhoduje s oracle, Greph je nesprávny. Ak sa `grep` a `rg` navzájom nezhodujú, scenár zaznamená tento nesúlad v `oracle_disagreement`, uvedie nástroj, ktorým sa Greph riadi v `greph_follows`, a porovnanie s druhým nástrojom nastaví na `skip`. V korpuse sa vyskytujú oba smery.

Textové scenáre sa porovnávajú s `grep` a `rg`, scenáre AST a prepisovania s `sg`. Výstup oracle sa zachytí raz a uloží do adresára `oracle/` každého scenára, takže bežné spustenie potrebuje iba PHP; externé nástroje sú potrebné len na zachytenie alebo obnovenie výstupu oracle.

Implementácia sa nachádza v `tests/Oracle/` a scenáre v `scenarios/text/`, `scenarios/ast/`, `scenarios/rewrite/` a `scenarios/edge/`.

## Štruktúra scenárov

Každý scenár je samostatný adresár:

```
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` deklaruje vzor, príznaky a cestu vyhľadávania. Voliteľný objekt `expectations` nastavuje režim porovnávania pre jednotlivé oracle (`exact`, `semantic` alebo `skip`); bez neho sa textové scenáre porovnávajú presne podľa `grep` a `rg` a sémanticky podľa `rg` JSON, zatiaľ čo scenáre AST a prepisovania sa porovnávajú s `sg`.

## Spustenie jedného scenára

Repozitár obsahuje malú sadu nástrojov CLI na prácu s jednotlivými scenármi. Sú to vývojové nástroje, nie vstupné body behu programu: nachádzajú sa vedľa spustiteľných súborov v `bin/`, ale nie sú súčasťou balíka Composer. Každý z nich prijíma názov scenára relatívne k `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
```

## Spustenie celej regresnej sady

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

Scenáre sa vždy spúšťajú po jednom. `--jobs N` sa prijíma a vypíše v súhrnnom riadku, ale nič nespúšťa paralelne ([#7](https://github.com/inline0/greph/issues/7)). V čerstvom klone `text/no-ignore` a `text/explicit-file-input` zlyhajú, pretože súbory s testovacími dátami v `setup/vendor/` nie sú odovzdané do repozitára ([#6](https://github.com/inline0/greph/issues/6)).

Regresná sada je podmienkou pre nové správanie. Nový príznak, hraničný prípad alebo oprava chyby si vyžaduje scenár, ktorý zachytí očakávané správanie voči oracle.

## Reportovanie súladu

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

`verify-compliance` samo nič nespúšťa. Načíta súbory oracle, skutočných výstupov a reportov, ktoré zanechalo posledné spustenie scenára, a vypíše, ktoré scenáre prešli, ktoré zlyhali a pri ktorých report ešte chýba. Najprv spustite `./bin/test-regression`. `--output report.json` tiež zapisuje report do JSON. Je to správny príkaz, ak chcete zistiť, „či je aktuálna vetva pripravená na vydanie“.

## Pracovný postup vývoja riadeného testami

Pri pridávaní funkcie:

1. Vytvorte adresár scenára s korpusom a príznakmi, ktoré preveria nové správanie.
2. Spustite `./bin/oracle <scenario>`, aby ste zachytili výstup kanonického nástroja.
3. Implementujte funkciu v `src/`.
4. Spustite `./bin/test-scenario <scenario>` a overte, že Greph zodpovedá oracle.
5. Spustite `./bin/test-regression --fast` a uistite sa, že sa nič iné nepokazilo.
6. Pred odovzdaním zmien spustite `composer verify`.

Pri oprave chyby:

1. Zachyťte zlyhávajúci vstup ako scenár.
2. Overte, že oracle vytvára očakávaný výstup.
3. Overte, že Greph ho nevytvára.
4. Opravte chybu.
5. Overte, že Greph sa teraz zhoduje s oracle.
6. Spustite `composer verify`.

Scenár zostáva v korpuse natrvalo, takže chyba sa nemôže znova objaviť bez zlyhania `composer test:oracle` (a `composer verify`).