# Tesztelés A Greph validálása három tesztréteggel történik: 1. **Egységtesztek** az elkülönített komponensekhez (elemzők, bejárók, kodekek, beállítások). 2. **Oracle-regressziós korpusz**, amely rögzített forgatókönyvkészleten összeveti a Greph kimenetét a kanonikus `grep`, `ripgrep` és `ast-grep` binárisokéval. 3. **Próbavezérelt funkciómátrix**, amely ellenőrzi a `rg` és `sg` burkolók igazolt felületét. A CI minden, a `main` ágra irányuló push és minden pull request (`.github/workflows/ci.yml`) esetén lefut. Ellenőrzi a kódolási szabványokat (`composer cs`), a statikus elemzést (`composer analyse`), a PHPUnit egység- és integrációs tesztcsomagjait (`composer test`), valamint a `composer audit` futtatását a PHP 8.4 verzióján. Az oracle-korpusz (`composer test:oracle`) nem része a CI-nak, a funkciómátrixot pedig kézzel kell újragenerálni a `php bin/feature-matrix` segítségével. A PHPUnit tesztcsomag tartalmaz egy tesztet, amely a mátrixot úgy generálja, hogy a felfelé irányuló `rg` és `sg` nem érhető el, majd ellenőrzi a jelentés szerkezetét, így nem bukik el attól, ha egyetlen próba visszafejlődik. ## Munka klónozott tárhelyből Az ezen az oldalon leírtakhoz a tárház klónjára van szükség. Mivel a Composer csomag már csak a `src/` elemet és a négy futtatható futtatókörnyezetet tartalmazza; a 0.2.3, a `tests/`, a `scenarios/`, a `benchmarks/` és a `bin/` fejlesztői szkriptek kimaradnak belőle. ```bash git clone https://github.com/inline0/greph cd greph composer install ``` ## A tesztek futtatása ```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 ``` A `composer verify` minden kiadás alapkövetelménye. Ha nem megy át, a módosítás nincs kész. ## Az oracle-modell A Greph oracle-vezérelt ellenőrzési modellt követ. Minden forgatókönyvhöz három parancs fut le: 1. **Oracle**: `grep`, `ripgrep` vagy `ast-grep`, a forgatókönyv-korpuszon rögzítve. 2. **Tényleges eredmény**: Greph, ugyanazon a korpuszon rögzítve. 3. **Összehasonlító**: strukturált különbségvizsgálat, amely soronként vagy szemantikailag ellenőrzi az egyenértékűséget. Ha a Greph eltér az oracle-től, akkor a Greph hibás. Ha a `grep` és a `rg` eltér egymástól, a forgatókönyv a `oracle_disagreement` alatt rögzíti az eltérést, megnevezi azt az eszközt, amelyet a Greph követ a `greph_follows` esetén, és a másik eszközzel való összehasonlítás állapotát `skip` értékre állítja. Mindkét irány előfordul a korpuszban. A szöveges forgatókönyvek összehasonlítása a `grep` és a `rg` ellen történik, az AST- és átírási forgatókönyveké pedig a `sg` ellen. Az oracle-kimenet egyszer kerül rögzítésre, és minden forgatókönyv `oracle/` könyvtárába kerül, ezért egy szokásos futtatáshoz csak a PHP szükséges; külső eszközök csak az oracle-kimenet rögzítéséhez vagy frissítéséhez kellenek. A megvalósítás helye: `tests/Oracle/`; a forgatókönyvek helye: `scenarios/text/`, `scenarios/ast/`, `scenarios/rewrite/` és `scenarios/edge/`. ## A forgatókönyvek felépítése Minden forgatókönyv önálló könyvtá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) ``` A `scenario.json` határozza meg a mintát, a jelzőket és a keresési útvonalat. Egy opcionális `expectations` objektum oracle-onként (`exact`, `semantic` vagy `skip`) állítja be az összehasonlítási módot; ennek hiányában a szöveges forgatókönyvek pontosan hasonlítják össze a `grep` és a `rg` értékét, a `rg` JSON értékét pedig szemantikailag, az AST- és átírási forgatókönyvek pedig a `sg` ellen hasonlítanak. ## Egyetlen forgatókönyv futtatása A tárház néhány CLI-eszközt kínál az egyes forgatókönyvekkel való munkához. Ezek fejlesztői eszközök, nem futtatókörnyezeti belépési pontok: a futtatókörnyezet bináris fájljai mellett találhatók a `bin/` könyvtárban, de nem részei a Composer csomagnak. Mindegyik a forgatókönyv nevét kéri, a `scenarios/` könyvtárhoz viszonyítva. ```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 ``` ## A teljes regressziós tesztcsomag futtatása ```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 ``` A forgatókönyvek mindig egyenként futnak le. A `--jobs N` elfogadott, és megjelenik az összefoglaló sorban, de nem futtat párhuzamosan semmit ([#7](https://github.com/inline0/greph/issues/7)). Friss klónban a `text/no-ignore` és a `text/explicit-file-input` hibát jelez, mert a `setup/vendor/` alatti tesztadatfájlok nincsenek a tárházban ([#6](https://github.com/inline0/greph/issues/6)). A regressziós tesztcsomag az új viselkedés elfogadási feltétele. Új jelzőhöz, új peremesethez vagy hibajavításhoz olyan forgatókönyv szükséges, amely oracle alapján rögzíti az elvárt viselkedést. ## Megfelelőségi jelentések ```bash ./bin/verify-compliance ``` A `verify-compliance` önmagában nem futtat semmit. Beolvassa az oracle-, a tényleges és a jelentésfájlokat, amelyeket az utolsó forgatókönyv-futtatás hagyott hátra, majd kiírja, mely forgatókönyvek mentek át, melyek buktak el, és melyekhez nem készült még jelentés. Először futtassa a `./bin/test-regression` eszközt. A `--output report.json` a jelentést JSON formátumban is elmenti. Ezt a parancsot érdemes futtatni, ha arra kíváncsi, hogy „készen áll-e az aktuális ág a kiadásra”. ## Tesztvezérelt fejlesztési munkafolyamat Funkció hozzáadásakor: 1. Hozzon létre egy forgatókönyv-könyvtárat a korpusszal és az új viselkedést kipróbáló jelzőkkel. 2. Futtassa a `./bin/oracle ` parancsot a kanonikus eszköz kimenetének rögzítéséhez. 3. Valósítsa meg a funkciót a `src/` helyen. 4. Futtassa a `./bin/test-scenario ` parancsot annak ellenőrzéséhez, hogy a Greph egyezik-e az oracle-lel. 5. Futtassa a `./bin/test-regression --fast` parancsot, hogy ellenőrizze, nem romlott-e el más működés. 6. Commit előtt futtassa a `composer verify` parancsot. Hiba javításakor: 1. Rögzítse a hibás bemenetet forgatókönyvként. 2. Ellenőrizze, hogy az oracle az elvárt kimenetet adja-e. 3. Ellenőrizze, hogy a Greph nem adja-e azt. 4. Javítsa ki a hibát. 5. Ellenőrizze, hogy a Greph most már egyezik-e az oracle-lel. 6. Futtassa a `composer verify` parancsot. A forgatókönyv végleg a korpuszban marad, így a hiba nem térhet vissza anélkül, hogy a `composer test:oracle` (és a `composer verify`) el ne bukna.