Test

Greph valideres med tre testlag:

1. Enhedstests for isolerede komponenter (parsers, gennemløbere, codecs, indstillinger).
2. Oracle-regressionskorpus, der sammenligner Greph-output med de kanoniske binærfiler grep, ripgrep og ast-grep på et fast sæt scenarier.
3. Sondedrevet funktionsmatrix, der fastslår det verificerede funktionsomfang for wrapperne rg og sg.

CI køres ved hvert push til main og ved hver pull request (.github/workflows/ci.yml). Den kører kodningsstandarder (composer cs), statisk analyse (composer analyse), PHPUnits enheds- og integrationstest (composer test) samt composer audit på PHP 8.4. Oracle-korpuset (composer test:oracle) indgår ikke i CI, og funktionsmatrixen gendannes manuelt med php bin/feature-matrix. PHPUnit-testpakken indeholder en test, der genererer matrixen med de opstrøms rg og sg markeret som utilgængelige og kontrollerer rapportens struktur, så testen ikke fejler, hvis en enkelt sonde går tilbage.

Arbejde fra en klon

Alt på denne side kræver en klon af repositoriet. Da 0.2.3-Composer-pakken kun indeholder src/ og de fire eksekverbare filer til kørsel, er tests/, scenarios/, benchmarks/ og udviklingsscripts i bin/ ikke med.

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

Kørsel af testene

# 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 er adgangskravet til enhver udgivelse. Hvis den ikke består, er ændringen ikke færdig.

Oracle-modellen

Greph følger en oracle-drevet verifikationsmodel. For hvert scenarie køres tre kommandoer:

1. Oracle: grep, ripgrep eller ast-grep, indsamlet for scenariekorpuset.
2. Faktisk resultat: Greph, indsamlet for det samme korpus.
3. Sammenligner: En struktureret sammenligning, der kontrollerer ækvivalens linje for linje eller semantisk.

Hvis Greph er uenig med oracle-resultatet, er Greph forkert. Hvis grep og rg er uenige, registrerer scenariet uenigheden under oracle_disagreement, angiver hvilket værktøj Greph følger i greph_follows, og sætter sammenligningen med det andet værktøj til skip. Begge retninger forekommer i korpuset.

Tekstscenarier sammenlignes med grep og rg, AST- og omskrivningsscenarier med sg. Oracle-output indsamles én gang og gemmes under hvert scenaries oracle/-mappe, så en normal kørsel kun kræver PHP; de eksterne værktøjer er kun nødvendige for at indsamle eller opdatere oracle-output.

Implementeringen ligger under tests/Oracle/, og scenarierne ligger under scenarios/text/, scenarios/ast/, scenarios/rewrite/ og scenarios/edge/.

Scenarieopsætning

Hvert scenarie er en selvstændig mappe:

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 angiver mønsteret, flagene og søgestien. Et valgfrit expectations-objekt angiver sammenligningstilstanden for hvert oracle (exact, semantic eller skip). Uden dette sammenlignes tekstscenarier præcist for grep og rg og semantisk for rg JSON, mens AST- og omskrivningsscenarier sammenlignes med sg.

Kørsel af et enkelt scenarie

Repositoryet har et lille sæt CLI'er til at arbejde med individuelle scenarier. De er udviklingsværktøjer, ikke runtime-indgange: De ligger sammen med runtime-binærfilerne i bin/, men er ikke en del af pakken Composer. Hver af dem tager scenarienavnet relativt til scenarios/.

# 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

Kørsel af hele regressionspakken

# 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

Scenarier køres altid ét ad gangen. --jobs N accepteres og vises i opsummeringslinjen, men kører ikke noget parallelt (#7). I en ny klon fejler text/no-ignore og text/explicit-file-input, fordi deres fixture-filer under setup/vendor/ ikke er med i repositoryet (#6).

Regressionspakken er adgangskravet for ny funktionalitet. Et nyt flag, et nyt grænsetilfælde eller en ny fejlrettelse kræver et scenarie, der registrerer den forventede adfærd ud fra et oracle.

Rapportering af overensstemmelse

./bin/verify-compliance

verify-compliance kører ikke noget selv. Den læser oracle-, actual- og rapportfilerne, som den seneste scenariekørsel efterlod, og viser, hvilke scenarier der består, hvilke der fejler, og hvilke der endnu ikke har en rapport. Kør først ./bin/test-regression. --output report.json skriver også rapporten som JSON. Det er den rette kommando, når du vil vide, "om den aktuelle gren er klar til udgivelse".

Testdrevet udviklingsforløb

Når du tilføjer en funktion:

1. Skriv en scenariemappe med korpuset og flagene, der afprøver den nye adfærd.
2. Kør ./bin/oracle <scenario> for at indsamle det kanoniske værktøjs output.
3. Implementér funktionen i src/.
4. Kør ./bin/test-scenario <scenario> for at kontrollere, at Greph stemmer overens med oracle-resultatet.
5. Kør ./bin/test-regression --fast for at sikre, at intet andet er gået tilbage.
6. Kør composer verify før commit.

Når du retter en fejl:

1. Gem det fejlende input som et scenarie.
2. Bekræft, at oracle-resultatet giver det forventede output.
3. Bekræft, at Greph ikke gør det.
4. Ret fejlen.
5. Bekræft, at Greph nu stemmer overens med oracle-resultatet.
6. Kør composer verify.

Scenariet forbliver permanent i korpuset, så fejlen ikke kan vende tilbage, uden at composer test:oracle (og composer verify) fejler.