# Testēšana Greph validē ar trim testu slāņiem: 1. **Vienību testi** izolētiem komponentiem (parsētājiem, staigātājiem, kodētājiem, opcijām). 2. **Orākula regresijas korpuss**, kas salīdzina Greph izvadi ar kanonisko `grep`, `ripgrep` un `ast-grep` bināro failu izvadi fiksētā scenāriju kopā. 3. **Zondēs balstīta funkciju matrica**, kas pārbauda `rg` un `sg` apvalku verificēto funkcionalitāti. CI darbojas katrā koda nosūtīšanas reizē uz `main` un katrā izmaiņu pieprasījumā (`.github/workflows/ci.yml`). Tā pārbauda kodēšanas standartus (`composer cs`), statisko analīzi (`composer analyse`), PHPUnit vienību un integrācijas testu kopas (`composer test`), kā arī `composer audit` vidē PHP 8.4. Orākula korpuss (`composer test:oracle`) nav iekļauts CI, un funkciju matrica tiek ģenerēta manuāli ar `php bin/feature-matrix`. PHPUnit kopā ir tests, kas ģenerē matricu, atzīmējot augšupējā līmeņa `rg` un `sg` kā nepieejamus, un pārbauda pārskata struktūru, tāpēc tas neizgāžas, ja kāda atsevišķa zonde regresē. ## Darbs ar klonētu repozitoriju Visam šajā lapā aprakstītajam nepieciešams repozitorija klons. Tā kā 0.2.3 Composer pakotnē ir tikai `src/` un četri izpildāmie izpildlaika faili, tajā nav iekļauts `tests/`, `scenarios/`, `benchmarks/` un izstrādes skripti no `bin/`. ```bash git clone https://github.com/inline0/greph cd greph composer install ``` ## Testu palaišana ```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` ir obligāts katram laidienam. Ja tas neizdodas, izmaiņas nav pabeigtas. ## Orākula modelis Greph izmanto orākulā balstītu verifikācijas modeli. Katram scenārijam tiek izpildītas trīs komandas: 1. **Orākuls**: `grep`, `ripgrep` vai `ast-grep`, kas tiek palaists scenāriju korpusā. 2. **Faktiskais rezultāts**: Greph, kas tiek palaists tajā pašā korpusā. 3. **Salīdzinātājs**: strukturēta salīdzināšana pa rindām vai pēc semantiskas ekvivalences. Ja Greph rezultāts nesakrīt ar orākulu, Greph ir kļūdains. Ja `grep` un `rg` rezultāti nesakrīt, scenārijā šī atšķirība tiek reģistrēta sadaļā `oracle_disagreement`, tiek norādīts rīks, kuram Greph seko sadaļā `greph_follows`, un salīdzinājums ar otru rīku tiek iestatīts uz `skip`. Korpusā ir sastopami abi varianti. Teksta scenāriji tiek salīdzināti ar `grep` un `rg`, AST un pārrakstīšanas scenāriji — ar `sg`. Orākula izvade tiek iegūta vienreiz un saglabāta katra scenārija `oracle/` direktorijā, tāpēc parastai palaišanai vajadzīgs tikai PHP; ārējie rīki nepieciešami vienīgi orākula izvades iegūšanai vai atjaunošanai. Implementācija atrodas `tests/Oracle/`, bet scenāriji — `scenarios/text/`, `scenarios/ast/`, `scenarios/rewrite/` un `scenarios/edge/`. ## Scenārija struktūra Katrs scenārijs ir pašpietiekams direktorijs: ``` 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` norāda paraugu, karogus un meklēšanas ceļu. Neobligāts objekts `expectations` nosaka salīdzināšanas režīmu katram orākulam (`exact`, `semantic` vai `skip`); ja tāda nav, teksta scenārijos `grep` un `rg` tiek salīdzināti precīzi, bet `rg` JSON — semantiski, savukārt AST un pārrakstīšanas scenāriji tiek salīdzināti ar `sg`. ## Atsevišķa scenārija palaišana Repozitorijā ir neliels CLI rīku komplekts darbam ar atsevišķiem scenārijiem. Tie ir izstrādes rīki, nevis izpildlaika ieejas punkti: tie atrodas blakus izpildlaika binārajiem failiem mapē `bin/`, taču nav iekļauti Composer pakotnē. Katrs no tiem pieņem scenārija nosaukumu attiecībā pret `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 ``` ## Pilnas regresijas testu kopas palaišana ```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āriji vienmēr tiek izpildīti pa vienam. `--jobs N` tiek pieņemts un atspoguļots kopsavilkuma rindā, taču tas neko neizpilda paralēli ([#7](https://github.com/inline0/greph/issues/7)). Tīrā klonā `text/no-ignore` un `text/explicit-file-input` neizdodas, jo to testa faili mapē `setup/vendor/` nav iekļauti repozitorijā ([#6](https://github.com/inline0/greph/issues/6)). Regresijas testu kopa ir vārtu pārbaude jaunai funkcionalitātei. Jauns karogs, jauns robežgadījums vai kļūdas labojums prasa scenāriju, kas fiksē gaidāmo uzvedību, salīdzinot ar orākulu. ## Atbilstības pārskatu veidošana ```bash ./bin/verify-compliance ``` `verify-compliance` pats neko neizpilda. Tas nolasa orākula, faktiskos rezultātus un pārskatu failus, ko atstājusi pēdējā palaistā scenārija komanda, un izvada, kuri scenāriji ir sekmīgi, kuri neizdodas un kuriem vēl nav pārskata. Vispirms palaidiet `./bin/test-regression`. `--output report.json` arī saglabā pārskatu kā JSON. Šī komanda jāpalaiž, ja vēlaties noskaidrot: “Vai pašreizējā zara izmaiņas ir gatavas laidienam?” ## Testos balstītas izstrādes darbplūsma Pievienojot funkciju: 1. Izveidojiet scenārija direktoriju ar korpusu un karogiem, kas pārbauda jauno uzvedību. 2. Palaidiet `./bin/oracle `, lai iegūtu kanoniskā rīka izvadi. 3. Ieviesiet funkciju mapē `src/`. 4. Palaidiet `./bin/test-scenario `, lai pārbaudītu, vai Greph atbilst orākulam. 5. Palaidiet `./bin/test-regression --fast`, lai pārliecinātos, ka nekas cits nav regresējis. 6. Pirms izmaiņu reģistrēšanas palaidiet `composer verify`. Labojot kļūdu: 1. Saglabājiet kļūdaino ievadi kā scenāriju. 2. Pārliecinieties, ka orākuls rada gaidīto izvadi. 3. Pārliecinieties, ka Greph to nerada. 4. Izlabojiet kļūdu. 5. Pārliecinieties, ka Greph tagad atbilst orākulam. 6. Palaidiet `composer verify`. Scenārijs vienmēr paliek korpusā, tāpēc kļūda nevar atkārtoties, neizraisot `composer test:oracle` (un `composer verify`) kļūmi.