Pereiti prie turinio

Testavimas

Peržiūrėti kaip Markdown Redaguoti per GitHub Dokumentacija: d105217

Greph tikrinamas trimis testų lygmenimis:

  1. Vienetų testai izoliuotiems komponentams (analizatoriams, peržiūros priemonėms, koduotuvams, parinktims).
  2. Etaloninių regresijų rinkinys, kuriame Greph išvestis lyginama su kanoniniais grep, ripgrep ir ast-grep dvejetainiais failais pagal fiksuotą scenarijų rinkinį.
  3. Užklausomis pagrįsta funkcijų matrica, patvirtinanti patikrintas rg ir sg apvalkalų funkcijas.

CI vykdomas kaskart, kai atliekamas siuntimas į main, ir kiekvienai sujungimo užklausai (.github/workflows/ci.yml). Jis tikrina kodavimo standartus (composer cs), statinę analizę (composer analyse), PHPUnit vienetų ir integravimo testų rinkinius (composer test) bei composer audit su PHP 8.4. Etaloninių testų rinkinys (composer test:oracle) nėra CI dalis, o funkcijų matrica iš naujo generuojama rankiniu būdu naudojant php bin/feature-matrix. PHPUnit rinkinyje yra testas, kuris generuoja matricą, kai pradiniai rg ir sg pažymėti kaip nepasiekiami, ir patikrina ataskaitos struktūrą, todėl testas nenutrūksta, jei sugenda viena užklausa.

Darbas su klonu

Norint atlikti viską, kas aprašyta šiame puslapyje, reikia turėti saugyklos kloną. Kadangi 0.2.3 Composer pakete yra tik src/ ir keturi vykdomieji failai; tests/, scenarios/, benchmarks/ ir kūrimo scenarijai, esantys bin/, į jį neįtraukiami.

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

Testų vykdymas

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 yra kiekvieno leidimo kriterijus. Jei jo nepavyksta įvykdyti, pakeitimas dar nebaigtas.

Etaloninis modelis

Greph taikomas etalonais pagrįstas tikrinimo modelis. Kiekvienam scenarijui vykdomos trys komandos:

  1. Etalonas: vykdomas grep, ripgrep arba ast-grep, o išvestis įrašoma pagal scenarijų rinkinį.
  2. Faktinė išvestis: vykdomas Greph, o išvestis įrašoma pagal tą patį rinkinį.
  3. Palygintuvas: struktūrinis skirtumų įrankis, tikrinantis atitiktį eilutė po eilutės arba pagal semantiką.

Jei Greph nesutampa su etalonu, vadinasi, Greph veikia netinkamai. Jei grep ir rg nesutampa, scenarijuje šis neatitikimas įrašomas į oracle_disagreement, nurodomas įrankis, kurio elgesiu Greph sekama pagal greph_follows, o palyginimas su kitu įrankiu nustatomas į skip. Rinkinyje pasitaiko abi kryptys.

Teksto scenarijai lyginami su grep ir rg, o AST ir perrašymo scenarijai – su sg. Etalonų išvestis įrašoma vieną kartą ir pateikiama kiekvieno scenarijaus oracle/ kataloge, todėl įprastam vykdymui reikia tik PHP; išoriniai įrankiai reikalingi tik etalonų išvesčiai užfiksuoti ar atnaujinti.

Įgyvendinimas yra tests/Oracle/, o scenarijai – scenarios/text/, scenarios/ast/, scenarios/rewrite/ ir scenarios/edge/.

Scenarijų struktūra

Kiekvienas scenarijus yra atskiras katalogas, kuriame yra visi reikalingi failai:

Kodas
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 nurodo šabloną, vėliavėles ir paieškos kelią. Pasirinktinis expectations objektas nustato kiekvieno etalono palyginimo režimą (exact, semantic arba skip); jei jo nėra, teksto scenarijai lygina grep ir rg tiksliai, o rg JSON – semantiškai; AST ir perrašymo scenarijai lyginami su sg.

Vieno scenarijaus vykdymas

Saugykloje yra keli maži CLI įrankiai atskiriems scenarijams vykdyti. Tai kūrimo įrankiai, o ne vykdymo aplinkos įvesties taškai: jie yra šalia vykdomųjų failų kataloge bin/, tačiau nėra Composer paketo dalis. Kiekvienam jų scenarijaus pavadinimas nurodomas scenarios/ atžvilgiu.

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

Viso regresijų rinkinio vykdymas

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

Scenarijai visada vykdomi po vieną. --jobs N priimamas ir parodomas suvestinės eilutėje, tačiau niekas nevykdoma lygiagrečiai (#7). Šviežiai sukurtoje klono kopijoje text/no-ignore ir text/explicit-file-input neveikia, nes jų failai iš katalogo setup/vendor/ nėra pateikiami (#6).

Regresijų rinkinys yra naujų funkcijų patikros kriterijus. Pridėjus vėliavėlę, naują ribinį atvejį ar klaidos taisymą, reikia sukurti scenarijų, kuris užfiksuotų numatomą elgesį pagal etaloną.

Atitikties ataskaitos

Shell
./bin/verify-compliance

verify-compliance pats nieko nevykdo. Jis nuskaito etalono, faktinės išvesties ir ataskaitų failus, kuriuos paliko paskutinį kartą vykdyti scenarijai, ir parodo, kurie scenarijai pavyko, kurie nepavyko, o kuriems dar nėra ataskaitos. Pirmiausia paleiskite ./bin/test-regression. --output report.json taip pat įrašo ataskaitą kaip JSON. Tai tinkama komanda, kai norite sužinoti, ar dabartinė šaka paruošta leidimui.

Testais pagrįstas kūrimo procesas

Pridėdami funkciją:

  1. Sukurkite scenarijaus katalogą su duomenų rinkiniu ir vėliavėlėmis, kurios išbando naują elgesį.
  2. Paleiskite ./bin/oracle <scenario>, kad užfiksuotumėte kanoninio įrankio išvestį.
  3. Įgyvendinkite funkciją src/.
  4. Paleiskite ./bin/test-scenario <scenario> ir patikrinkite, ar Greph atitinka etaloną.
  5. Paleiskite ./bin/test-regression --fast ir įsitikinkite, kad kitos funkcijos nenustojo veikti.
  6. Prieš pateikdami pakeitimus, paleiskite composer verify.

Taisydami klaidą:

  1. Užfiksuokite klaidingą įvestį kaip scenarijų.
  2. Patvirtinkite, kad etalonas pateikia numatytą išvestį.
  3. Patvirtinkite, kad Greph jos nepateikia.
  4. Ištaisykite klaidą.
  5. Patvirtinkite, kad Greph dabar atitinka etaloną.
  6. Paleiskite composer verify.

Scenarijus visam laikui lieka duomenų rinkinyje, todėl klaida negalės pasikartoti, kol nepavyks composer test:oracle (ir composer verify).