Preskočiť na obsah

Testovanie

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na d105217

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é.

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

Spustenie testov

Shell
# 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:

Kód
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/.

Shell
# 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

Shell
# 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). 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).

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

Shell
./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).