Ugrás a tartalomhoz

Tesztelés

Megtekintés Markdownként Szerkesztés itt: GitHub Dokumentáció itt: d105217

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.

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

A tesztek futtatása

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

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:

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)

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.

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

A teljes regressziós tesztcsomag futtatása

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

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

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

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