Pengujian golden file

Spec Spec: ISO/IEC/IEEE 29119-4 ISO/IEC/IEEE 29119-4 Spec Spec: ISO/IEC 25010 ISO/IEC 25010 Evidence ✓ Test-backed Evidence: Test-backed

Sekilas pandang

Golden file adalah rekaman “beginilah seharusnya keluaran yang benar” yang dibandingkan oleh pengujian setiap kali dijalankan. NextPDF memakai golden untuk menangkap perubahan yang tidak disengaja: stream yang terkompresi secara berbeda, paragraf yang bergeser, atau koordinat yang melenceng. Halaman ini menjelaskan cara kerjanya dan bagaimana sebuah golden tetap tepercaya, bukan menjadi rujukan usang yang tidak dibaca siapa pun.

Mengapa ini penting

Proses pembuatan PDF adalah pipeline panjang dengan banyak titik tempat penyimpangan bisa terjadi diam-diam. Refaktor yang “tidak mengubah apa pun” bisa diam-diam mengubah urutan operator, mengubah matriks transformasi, atau menggeser sel tabel sedikit saja. Pengujian unit jarang menangkap hal ini: pengujian itu memverifikasi nilai yang Anda ingat untuk diperiksa, bukan ribuan byte yang tidak Anda periksa. Teknik berbasis struktur dan berbasis spesifikasi mendeteksi kesalahan yang berbeda, dan tidak ada yang mencakup yang lain (ISO/IEC/IEEE 29119-4, Annex A). Golden file adalah spesifikasi-lewat-contoh yang mematok seluruh keluaran, bukan hanya satu asersi.

Risikonya berlaku dua arah. Golden yang terlalu ketat gagal pada setiap perubahan tak berbahaya dan disahkan ulang secara membabi buta hingga tidak lagi membuktikan apa pun. Golden yang terlalu longgar membiarkan regresi yang sebenarnya lolos. Menemukan keseimbangan yang tepat itulah inti tantangannya.

Versi singkatnya

• Sebuah golden file adalah keluaran rujukan yang dipatok, dihasilkan dari perilaku mesin yang terbukti baik, lalu di-commit ke repositori.
• Pengujian golden membuat ulang keluaran lalu membandingkannya (diff) dengan rujukan yang dipatok; perbedaan apa pun menggagalkan pengujian dan memerlukan keputusan manusia.
• NextPDF membandingkan pada tingkat yang bermakna tetapi stabil: teks yang diekstrak dan operator struktural yang dinormalisasi, bukan byte mentah, karena byte mentah membawa derau (timestamp, urutan subset, kompresi) yang bukan regresi.
• Memperbarui golden adalah tindakan yang disengaja dan ditinjau, di balik saklar GOLDEN_UPDATE yang eksplisit — tidak pernah berupa “menerima apa pun yang berubah” secara otomatis.
• Golden berbeda dari pengujian snapshot dan karakterisasi dalam satu hal yang menentukan: golden tidak pernah diperbarui otomatis.

Bagaimana NextPDF menanganinya

Infrastruktur golden mesin memakai diff dua lapis yang eksplisit, bukan perbandingan byte:

1. Generate Render the fixture input through the current engine.
2. Layer 1 — text Extract human-readable text from the content stream; diff against the text golden. Catches dropped or reordered content and encoding regressions.
3. Layer 2 — structure Extract ordered PDF operators, normalise coordinates to a fixed precision, diff against the operator golden. Catches layout shifts and broken structure.
4. Decide Any diff fails the test; a human judges whether it is a regression or an intended change.

Cara perbandingan golden NextPDF berjalan: hasilkan PDF, ekstrak lapisan-lapisan yang bermakna (teks, lalu operator struktural yang dinormalisasi), bandingkan masing-masing dengan rujukan yang dipatok, dan gagalkan dengan laporan yang mudah dibaca manusia pada setiap perbedaan.

Apa yang dengan sengaja tidak dibandingkan sama pentingnya dengan apa yang dibandingkan. Keluaran byte mentah dikecualikan karena timestamp, urutan subset font, dan kompresi stream membuatnya rapuh tanpa membuatnya lebih benar. Perbandingan gambar tingkat piksel dikecualikan dari tingkat ini karena membutuhkan renderer eksternal dan memasukkan variansi lingkungan. Koordinat floating-point dinormalisasi ke presisi tetap agar derau pembulatan yang tak bermakna tidak menyamar sebagai regresi. Inilah perbedaan antara golden yang menguji perilaku dan golden yang menguji derau lingkungan sesaat.

Pilihan ini juga menentukan profil reproduksibilitas halaman ini: struktural. NextPDF mendokumentasikan tiga profil — bitwise (byte persisnya tereproduksi), structural (graf objek dan urutan operator tereproduksi, dengan mengizinkan variansi tingkat byte yang tidak berbahaya), dan semantic (maknanya tereproduksi). Pengujian golden pada tingkat ini menegaskan profil struktural berdasarkan rancangannya. Itulah sebabnya rujukannya bertahan saat ada peningkatan versi pustaka kompresi, tetapi tetap gagal pada tabel yang bergeser.

Human-factors note: Human-factors note

Mode kegagalan yang berbahaya dari pengujian golden bersifat sosial, bukan teknis. Ketika sebuah golden terlalu ketat, setiap perubahan yang tak terkait membuatnya merah, dan respons manusia yang rasional adalah berhenti membaca diff lalu mengesahkannya ulang. Pada titik itu pengujian tetap berjalan, tetap “lulus”, dan tidak membuktikan apa pun. NextPDF melindungi diri dari hal ini dengan membandingkan pada lapisan yang bermakna alih-alih lapisan byte, dan dengan menjadikan pembaruan sebagai saklar yang digunakan secara sadar dan ditinjau — sehingga golden yang berubah adalah pertanyaan yang harus dijawab, bukan kotak centang yang harus dibereskan.

Apa kata buktinya

Evidence ✓ Test-backed Evidence: Test-backed Perbandingan dua lapis (ekstraksi teks, lalu perbandingan operator struktural yang dinormalisasi) adalah metodologi golden mesin yang terdokumentasi secara mandiri, sementara perbandingan byte mentah, diff gambar, dan float persis secara eksplisit berada di luar cakupan karena alasan-alasan di atas. Suite golden adalah suite pengujian yang dideklarasikan dan dapat dijalankan terpisah, berbeda dari suite snapshot dan karakterisasi.

Evidence ✓ Test-backed Evidence: Test-backed Mekanisme kejujurannya konkret: rujukan golden adalah artefak yang dihasilkan, bukan ditulis tangan. Penimpaan rujukan tersebut dibatasi oleh saklar lingkungan GOLDEN_UPDATE yang eksplisit, yang didokumentasikan sebagai operasi yang jarang dilakukan dan selalu ditinjau. Sebaliknya, pengujian snapshot di mesin membuat ulang rujukan pada saat dijalankan pertama kali dan mengakui penyimpangan lewat flag pembaruan. Dan pengujian karakterisasi mengunci perilaku lama tanpa mengklaim bahwa perilaku itu benar. Ketiganya secara sengaja merupakan alat yang berbeda.

Evidence § Standard-backed Evidence: Standard-backed Golden adalah spesifikasi-lewat-contoh. Spec Spec: ISO/IEC/IEEE 29119-4, Annex A ISO/IEC/IEEE 29119-4 Annex A mencatat bahwa teknik berbasis spesifikasi dan berbasis struktur menangkap kelas kesalahan yang berbeda dan bahwa sebuah strategi sebaiknya menggabungkan keduanya. Itulah sebabnya golden berdampingan dengan, bukan menggantikan, pengujian unit dan struktural dalam piramida pengujian.

Contoh praktis

Secara mekanis, pengujian golden itu sederhana; disiplinnya ada pada alur kerja di sekitarnya:

<?php

declare(strict_types=1);

// 1. The fixture: a fixed HTML input committed next to the test.
//    tests/Golden/fixtures/html-inputs/002-basic-table.html

// 2. The pinned references, generated once from known-good behaviour:
//    002-basic-table.text.golden       (Layer 1 — extracted text)
//    002-basic-table.operators.golden  (Layer 2 — normalised operators)

// 3. The run compares; ANY difference fails:
//    vendor/bin/phpunit --testsuite Golden

// 4. An intended behaviour change is the ONLY time references move,
//    and it is explicit and reviewed — never automatic:
//    GOLDEN_UPDATE=1 vendor/bin/phpunit --testsuite Golden
//
//    The regenerated *.golden files land in the diff of the same change
//    that altered behaviour, so a reviewer sees the output delta next to
//    the code delta and signs off on both together.

Yang penting dari contoh ini adalah prosesnya. Kode pengujian hanya membandingkan (diff). Yang membuat golden tepercaya adalah bahwa rujukan yang berubah ditinjau sebagai keluaran dalam perubahan yang sama yang mengubah mesin.

Kesalahpahaman umum

Kesalahan paling umum adalah memperlakukan pengujian golden sebagai pengujian byte demi byte. Golden NextPDF bukanlah byte berkas — melainkan teks yang diekstrak dan operator strukturalnya yang dinormalisasi. Memverifikasi byte mentah akan gagal pada versi zlib baru, tag subset yang berbeda, atau timestamp yang dibuat ulang, yang tidak satu pun merupakan regresi. Pengujian itu akan disahkan ulang sampai tidak berguna lagi dalam waktu seminggu. (Apabila byte yang persis memang harus tereproduksi, itu adalah profil reproduksibilitas bitwise yang terpisah dan lebih ketat, bukan golden.)

Kesalahan kedua adalah menganggap suite golden yang hijau membuktikan kebenaran. Itu membuktikan ketiadaan perubahan. Golden yang dihasilkan dari keluaran yang bermasalah akan setia melindungi bug itu. Golden menjaga dari regresi terhadap baseline yang terbukti baik; golden tidak menetapkan bahwa baseline itu memang baik. Untuk itulah tingkat unit, struktural, dan konformansi ada.

Batasan dan lingkup

Pengujian golden menjawab tepat satu pertanyaan: apakah keluaran berubah dari rujukan yang dipatok. Pengujian itu tidak menyatakan apakah rujukan tersebut pernah benar. Pengujian itu juga tidak mengukur performa, konformansi, atau keamanan. Itu adalah tingkat lain. Ukuran korpus fixture, tingkat kelulusan suite, dan setiap angka cakupan adalah sinyal kualitas yang dinamis, dihasilkan dari artefak continuous integration dan dipublikasikan bersama build. Angka-angka itu sengaja tidak dicantumkan di sini, tempat mereka bisa menjadi usang.

Tata letak direktori persisnya, internal komparator, dan saklar pembaruan dimiliki oleh infrastruktur pengujian mesin dan dapat berkembang. Konfigurasi pengujian adalah otoritasnya jika suatu saat berbeda dengan penjelasan ini. Halaman ini tidak membuat klaim apa pun tentang tooling snapshot atau golden pustaka lain mana pun.

Dokumen terkait

• Piramida pengujian NextPDF — tempat tingkat golden berada di antara kelima tingkat dan apa yang biasanya dibuktikannya.
• Pengujian mutasi, dijelaskan — bagaimana NextPDF memeriksa bahwa pengujiannya, termasuk golden, benar-benar mendeteksi kesalahan.
• Tipe ketat, di mana-mana — analisis statis yang menghilangkan satu kelas cacat sebelum golden mana pun dijalankan.

Glosarium

• Golden file — keluaran rujukan yang dipatok, dihasilkan dari perilaku mesin yang terbukti baik dan di-commit, yang dibandingkan (diff) oleh pengujian setiap kali dijalankan. Tidak pernah diperbarui otomatis.
• Diff dua lapis — perbandingan golden NextPDF: teks yang diekstrak (Lapis 1) ditambah operator struktural yang dinormalisasi (Lapis 2), alih-alih byte mentah.
• Pengujian snapshot — teknik terkait tetapi berbeda, di mana rujukan dibuat ulang pada saat dijalankan pertama kali dan penyimpangan diakui lewat flag pembaruan.
• Pengujian karakterisasi — pengujian yang mengunci perilaku yang ada tanpa menegaskan bahwa perilaku itu benar, biasanya agar refaktor aman.
• Profil reproduksibilitas — tingkat di mana keluaran harus tereproduksi: bitwise (byte persis), structural (graf objek dan urutan operator, dengan variansi byte yang tidak berbahaya diizinkan), atau semantic (makna). Pengujian golden di sini menegaskan profil struktural.
• GOLDEN_UPDATE — saklar lingkungan eksplisit yang mengizinkan penimpaan rujukan golden; operasi yang jarang dilakukan dan ditinjau.