Testen

Greph wordt gevalideerd met drie testlagen:

1. Unit-tests voor geïsoleerde componenten (parsers, walkers, codecs, opties).
2. Regressiecorpus van het orakel dat de uitvoer van Greph vergelijkt met de canonieke binaire bestanden van grep, ripgrep en ast-grep aan de hand van een vaste reeks scenario's.
3. Functiematrix op basis van probes die het geverifieerde oppervlak van de wrappers rg en sg controleert.

CI wordt uitgevoerd bij elke push naar main en bij elke pull request (.github/workflows/ci.yml). Het voert coderingsstandaarden (composer cs), statische analyse (composer analyse), de unit- en integratietestsuites van PHPUnit (composer test) en composer audit uit op PHP 8.4. Het orakelcorpus (composer test:oracle) maakt geen deel uit van CI en de functiematrix wordt handmatig opnieuw gegenereerd met php bin/feature-matrix. De suite PHPUnit bevat een test die de matrix genereert terwijl de upstream rg en sg als niet beschikbaar zijn gemarkeerd, en controleert de structuur van het rapport. Daardoor mislukt de test niet als één probe een regressie vertoont.

Werken vanuit een kloon

Voor alles op deze pagina is een kloon van de repository nodig. Omdat het Composer-pakket van 0.2.3 alleen src/ en de vier runtime-uitvoerbare bestanden bevat, zijn tests/, scenarios/, benchmarks/ en de ontwikkelscripts in bin/ ervan uitgesloten.

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

De tests uitvoeren

# 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 is de norm voor elke release. Als deze niet slaagt, is de wijziging niet af.

Het orakelmodel

Greph volgt een verificatiemodel dat door een orakel wordt gestuurd. Voor elk scenario worden drie opdrachten uitgevoerd:

1. Orakel: grep, ripgrep of ast-grep, vastgelegd voor het scenariocorpus.
2. Werkelijk: Greph, vastgelegd voor hetzelfde corpus.
3. Vergelijker: een gestructureerde diff die gelijkwaardigheid per regel of semantisch controleert.

Als Greph afwijkt van het orakel, is Greph onjuist. Als grep en rg van elkaar afwijken, legt het scenario het verschil vast onder oracle_disagreement, vermeldt het welke tool Greph volgt in greph_follows en stelt het de vergelijking met de andere tool in op skip. Beide richtingen komen voor in het corpus.

Tekstscenario's worden vergeleken met grep en rg; AST- en herschrijvingsscenario's met sg. De orakeluitvoer wordt eenmaal vastgelegd en opgeslagen in de map oracle/ van elk scenario. Voor een normale uitvoering is daarom alleen PHP nodig; de externe tools zijn alleen nodig om orakeluitvoer vast te leggen of te vernieuwen.

De implementatie staat onder tests/Oracle/ en de scenario's staan onder scenarios/text/, scenarios/ast/, scenarios/rewrite/ en scenarios/edge/.

Scenariostructuur

Elk scenario is een zelfstandige map:

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 definieert het patroon, de flags en het zoekpad. Een optioneel object expectations stelt de vergelijkingsmodus per orakel in (exact, semantic of skip). Zonder dit object vergelijken tekstscenario's grep en rg exact en de rg JSON semantisch; AST- en herschrijvingsscenario's vergelijken met sg.

Eén scenario uitvoeren

De repository bevat een kleine set CLI's om met afzonderlijke scenario's te werken. Dit zijn ontwikkeltools, geen runtime-entrypoints: ze staan naast de runtime-binaire bestanden in bin/, maar maken geen deel uit van het Composer-pakket. Elke CLI gebruikt de scenarionaam relatief ten opzichte van 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

De volledige regressiesuite uitvoeren

# 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

Scenario's worden altijd één voor één uitgevoerd. --jobs N wordt geaccepteerd en weergegeven in de samenvattingsregel, maar voert niets parallel uit (#7). In een nieuwe kloon mislukken text/no-ignore en text/explicit-file-input, omdat hun fixturebestanden in setup/vendor/ niet zijn opgeslagen (#6).

De regressiesuite is de poortwachter voor nieuw gedrag. Voor een nieuwe flag, een nieuw randgeval of een bugfix is een scenario nodig waarin het verwachte gedrag aan de hand van een orakel wordt vastgelegd.

Nalevingsrapportage

./bin/verify-compliance

verify-compliance voert zelf niets uit. Het leest de orakel-, werkelijke en rapportbestanden die de laatste scenariorun heeft achtergelaten en geeft aan welke scenario's slagen, welke mislukken en voor welke nog geen rapport bestaat. Voer eerst ./bin/test-regression uit. --output report.json schrijft het rapport ook weg als JSON. Dit is de juiste opdracht als u wilt weten: "is de huidige branch klaar voor release?".

Testgestuurde ontwikkelworkflow

Bij het toevoegen van een functie:

1. Schrijf een scenariomap met het corpus en de flags die het nieuwe gedrag testen.
2. Voer ./bin/oracle <scenario> uit om de uitvoer van de canonieke tool vast te leggen.
3. Implementeer de functie in src/.
4. Voer ./bin/test-scenario <scenario> uit om te controleren of Greph overeenkomt met het orakel.
5. Voer ./bin/test-regression --fast uit om te controleren of er niets anders is verslechterd.
6. Voer composer verify uit voordat u commit.

Bij het oplossen van een bug:

1. Leg de mislukte invoer vast als scenario.
2. Controleer of het orakel de verwachte uitvoer produceert.
3. Controleer of Greph dat niet doet.
4. Los de bug op.
5. Controleer of Greph nu overeenkomt met het orakel.
6. Voer composer verify uit.

Het scenario blijft permanent in het corpus, zodat de bug niet terug kan komen zonder dat composer test:oracle (en composer verify) mislukken.