Lewati ke konten

Pengujian

Lihat sebagai Markdown Edit di GitHub Dokumentasi di d105217

Greph divalidasi dengan tiga lapisan pengujian:

  1. Pengujian unit untuk komponen terpisah (parser, walker, codec, opsi).
  2. Korpus regresi oracle yang membandingkan keluaran Greph dengan biner grep, ripgrep, dan ast-grep kanonis pada sekumpulan skenario tetap.
  3. Matriks fitur berbasis probe yang memastikan permukaan terverifikasi dari wrapper rg dan sg.

CI berjalan pada setiap push ke main dan setiap pull request (.github/workflows/ci.yml). CI menjalankan standar pengodean (composer cs), analisis statis (composer analyse), rangkaian pengujian unit dan integrasi PHPUnit (composer test), serta composer audit pada PHP 8.4. Korpus oracle (composer test:oracle) tidak menjadi bagian dari CI, dan matriks fitur dibuat ulang secara manual dengan php bin/feature-matrix. Rangkaian PHPUnit mencakup pengujian yang membuat matriks dengan rg dan sg upstream ditandai tidak tersedia, lalu memeriksa struktur laporan, sehingga pengujian tidak gagal saat satu probe mengalami regresi.

Bekerja dari klon

Semua hal di halaman ini memerlukan klon repositori. Karena 0.2.3, paket Composer hanya berisi src/ dan keempat executable runtime; tests/, scenarios/, benchmarks/, serta skrip pengembangan di bin/ tidak disertakan di dalamnya.

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

Menjalankan pengujian

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 adalah standar untuk setiap rilis. Jika tidak lolos, perubahan belum selesai.

Model oracle

Greph menggunakan model verifikasi berbasis oracle. Untuk setiap skenario, tiga perintah dijalankan:

  1. Oracle: grep, ripgrep, atau ast-grep, diambil berdasarkan korpus skenario.
  2. Aktual: Greph, diambil berdasarkan korpus yang sama.
  3. Pembanding: perbedaan terstruktur yang memeriksa kesetaraan baris demi baris atau secara semantik.

Jika Greph berbeda dari oracle, berarti Greph salah. Jika grep dan rg berbeda satu sama lain, skenario mencatat perbedaan itu di oracle_disagreement, menyebutkan tool yang diikuti Greph di greph_follows, dan menetapkan perbandingan dengan tool lainnya ke skip. Kedua arah perbedaan muncul di dalam korpus.

Skenario teks dibandingkan dengan grep dan rg, sedangkan skenario AST dan penulisan ulang dibandingkan dengan sg. Keluaran oracle diambil satu kali dan dikomit di direktori oracle/ masing-masing skenario, sehingga proses normal hanya memerlukan PHP; tool eksternal hanya diperlukan untuk mengambil atau memperbarui keluaran oracle.

Implementasi berada di tests/Oracle/ dan skenario berada di scenarios/text/, scenarios/ast/, scenarios/rewrite/, dan scenarios/edge/.

Tata letak skenario

Setiap skenario merupakan direktori mandiri:

Kode
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 mendeklarasikan pola, flag, dan jalur pencarian. Objek expectations opsional menetapkan mode perbandingan untuk setiap oracle (exact, semantic, atau skip); tanpa objek ini, skenario teks membandingkan grep dan rg secara tepat serta rg JSON secara semantik, sedangkan skenario AST dan penulisan ulang membandingkan dengan sg.

Menjalankan satu skenario

Repositori ini memiliki beberapa CLI kecil untuk bekerja dengan tiap skenario. CLI ini adalah tool pengembangan, bukan titik masuk runtime: CLI berada bersama biner runtime di bin/, tetapi bukan bagian dari paket Composer. Setiap CLI menerima nama skenario relatif terhadap scenarios/.

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

Menjalankan seluruh rangkaian regresi

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

Skenario selalu dijalankan satu per satu. --jobs N diterima dan ditampilkan kembali di baris ringkasan, tetapi tidak menjalankan apa pun secara paralel (#7). Pada klon baru, text/no-ignore dan text/explicit-file-input gagal karena file fixture di setup/vendor/ tidak dikomit (#6).

Rangkaian regresi menjadi gerbang untuk perilaku baru. Flag baru, kasus tepi baru, atau perbaikan bug baru memerlukan skenario yang merekam perilaku yang diharapkan berdasarkan oracle.

Pelaporan kepatuhan

Shell
./bin/verify-compliance

verify-compliance tidak menjalankan apa pun dengan sendirinya. Perintah ini membaca berkas oracle, aktual, dan laporan yang ditinggalkan oleh skenario terakhir, lalu menampilkan skenario mana yang lulus, gagal, dan belum memiliki laporan. Jalankan ./bin/test-regression terlebih dahulu. --output report.json juga menulis laporan sebagai JSON. Ini adalah perintah yang tepat untuk dijalankan saat Anda ingin mengetahui “apakah cabang saat ini siap dirilis”.

Alur kerja pengembangan berbasis pengujian

Saat menambahkan fitur:

  1. Tulis direktori skenario dengan korpus dan flag yang menguji perilaku baru.
  2. Jalankan ./bin/oracle <scenario> untuk mengambil keluaran tool kanonis.
  3. Implementasikan fitur di src/.
  4. Jalankan ./bin/test-scenario <scenario> untuk memverifikasi bahwa Greph cocok dengan oracle.
  5. Jalankan ./bin/test-regression --fast untuk memastikan tidak ada hal lain yang mengalami regresi.
  6. Jalankan composer verify sebelum melakukan commit.

Saat memperbaiki bug:

  1. Ambil masukan yang gagal sebagai sebuah skenario.
  2. Pastikan oracle menghasilkan keluaran yang diharapkan.
  3. Pastikan Greph tidak menghasilkan keluaran tersebut.
  4. Perbaiki bug.
  5. Pastikan Greph kini cocok dengan oracle.
  6. Jalankan composer verify.

Skenario tetap berada di dalam korpus, sehingga bug tidak dapat muncul kembali tanpa menyebabkan kegagalan pada composer test:oracle (dan composer verify).