# Test Etme Greph üç test katmanıyla doğrulanır: 1. Yalıtılmış bileşenler (ayrıştırıcılar, gezginler, kodlayıcılar, seçenekler) için **Birim testleri**. 2. Sabit bir senaryo kümesinde Greph çıktısını kanonik `grep`, `ripgrep` ve `ast-grep` ikili dosyalarıyla karşılaştıran **Doğruluk regresyon külliyatı**. 3. `rg` ve `sg` sarmalayıcılarının doğrulanmış kapsamını denetleyen **Yoklamaya dayalı özellik matrisi**. CI, `main` dalına yapılan her gönderimde ve her çekme isteğinde (`.github/workflows/ci.yml`) çalışır. Kodlama standartlarını (`composer cs`), statik analizi (`composer analyse`), PHPUnit birim ve entegrasyon paketlerini (`composer test`) ve `composer audit` öğesini PHP 8.4 üzerinde çalıştırır. Doğruluk külliyatı (`composer test:oracle`) CI kapsamında değildir; özellik matrisi ise `php bin/feature-matrix` kullanılarak elle yeniden oluşturulur. PHPUnit paketi, yukarı akıştaki `rg` ve `sg` kullanılamaz olarak işaretlenmişken matrisi oluşturan ve raporun yapısını denetleyen bir test içerir; böylece tek bir yoklamanın gerilemesi CI'yı bozmaz. ## Klondan çalışma Bu sayfadaki her şey için deponun klonu gerekir. 0.2.3 nedeniyle Composer paketi yalnızca `src/` ve çalışma zamanında kullanılan dört çalıştırılabilir dosyayı içerir; `tests/`, `scenarios/`, `benchmarks/` ve `bin/` içindeki geliştirme betikleri pakete dahil edilmez. ```bash git clone https://github.com/inline0/greph cd greph composer install ``` ## Testleri çalıştırma ```bash # 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` her sürüm için ölçüttür. Başarısız olursa değişiklik tamamlanmış sayılmaz. ## Doğruluk modeli Greph, doğruluk kaynağı odaklı bir doğrulama modeli izler. Her senaryo için üç komut çalışır: 1. **Doğruluk kaynağı**: Senaryo külliyatına karşı çalıştırılan `grep`, `ripgrep` veya `ast-grep`. 2. **Gerçek çıktı**: Aynı külliyata karşı çalıştırılan Greph. 3. **Karşılaştırıcı**: Satır satır veya anlamsal eşdeğerliği denetleyen yapılandırılmış bir fark. Greph doğruluk kaynağıyla uyuşmuyorsa Greph yanlıştır. `grep` ve `rg` birbiriyle uyuşmuyorsa senaryo bu uyuşmazlığı `oracle_disagreement` altında kaydeder, aracın `greph_follows` içinde izlediği Greph adını belirtir ve diğer araca karşılaştırmayı `skip` olarak işaretler. Külliyatta her iki durum da görülür. Metin senaryoları `grep` ve `rg` ile, AST ve yeniden yazma senaryoları ise `sg` ile karşılaştırılır. Doğruluk kaynağı çıktısı bir kez alınır ve her senaryonun `oracle/` dizininde saklanır; bu nedenle olağan bir çalıştırmada yalnızca PHP gerekir. Harici araçlar yalnızca doğruluk kaynağı çıktısını almak veya yenilemek için gereklidir. Uygulama `tests/Oracle/` altında, senaryolar ise `scenarios/text/`, `scenarios/ast/`, `scenarios/rewrite/` ve `scenarios/edge/` altında yer alır. ## Senaryo düzeni Her senaryo kendi kendine yeten bir dizindir: ``` 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`, deseni, bayrakları ve arama yolunu tanımlar. İsteğe bağlı `expectations` nesnesi, her doğruluk kaynağı için (`exact`, `semantic` veya `skip`) karşılaştırma modunu belirler. Bu nesne yoksa metin senaryolarında `grep` ve `rg` tam olarak, `rg` JSON ise anlamsal olarak karşılaştırılır; AST ve yeniden yazma senaryoları da `sg` ile karşılaştırılır. ## Tek senaryo çalıştırma Depoda tek tek senaryolar üzerinde çalışmaya yönelik küçük bir CLI araçları kümesi bulunur. Bunlar çalışma zamanı giriş noktaları değil, geliştirme araçlarıdır: çalışma zamanı ikili dosyalarının yanında `bin/` içinde yer alırlar, ancak Composer paketinin parçası değildirler. Her biri, senaryo adını `scenarios/` öğesine göreli olarak alır. ```bash # 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 ``` ## Tüm regresyon paketini çalıştırma ```bash # 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 ``` Senaryolar her zaman birer birer çalıştırılır. `--jobs N` kabul edilip özet satırında gösterilir, ancak paralel hiçbir işlem yürütmez ([#7](https://github.com/inline0/greph/issues/7)). Yeni klonlanmış bir depoda `text/no-ignore` ve `text/explicit-file-input` başarısız olur; çünkü `setup/vendor/` altındaki test dosyaları depoya eklenmemiştir ([#6](https://github.com/inline0/greph/issues/6)). Regresyon paketi, yeni davranışlar için geçiş ölçütüdür. Yeni bir bayrak, uç durum veya hata düzeltmesi, doğruluk kaynağına göre beklenen davranışı kaydeden bir senaryo gerektirir. ## Uygunluk raporlaması ```bash ./bin/verify-compliance ``` `verify-compliance` hiçbir şeyi kendi başına çalıştırmaz. Son senaryo çalıştırmalarının geride bıraktığı doğruluk kaynağı, gerçek çıktı ve rapor dosyalarını okur; hangi senaryoların geçtiğini, başarısız olduğunu ve henüz raporu bulunmadığını yazdırır. Önce `./bin/test-regression` çalıştırın. `--output report.json` raporu ayrıca JSON olarak yazar. “Geçerli dal sürüme hazır mı?” sorusunun yanıtını öğrenmek istediğinizde çalıştırmanız gereken doğru komut budur. ## Test odaklı geliştirme iş akışı Bir özellik eklerken: 1. Yeni davranışı çalıştıran korpus ve bayraklarla bir senaryo dizini yazın. 2. Kanonik aracın çıktısını kaydetmek için `./bin/oracle ` komutunu çalıştırın. 3. Özelliği `src/` içinde uygulayın. 4. Greph sonucunun oracle ile eşleştiğini doğrulamak için `./bin/test-scenario ` komutunu çalıştırın. 5. Başka bir şeyin bozulmadığından emin olmak için `./bin/test-regression --fast` komutunu çalıştırın. 6. Commit etmeden önce `composer verify` komutunu çalıştırın. Bir hatayı düzeltirken: 1. Hatalı girdiyi bir senaryo olarak kaydedin. 2. Oracle'ın beklenen çıktıyı ürettiğini doğrulayın. 3. Greph aracının bunu üretmediğini doğrulayın. 4. Hatayı düzeltin. 5. Greph aracının artık oracle ile eşleştiğini doğrulayın. 6. `composer verify` komutunu çalıştırın. Senaryo kalıcı olarak korpusta kalır; böylece `composer test:oracle` (ve `composer verify`) başarısız olmadan hata yeniden ortaya çıkamaz.