Altın dosya (golden-file) testi

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

Bir bakışta

Altın dosya, “doğru çıktı böyle görünür” diye kaydedilmiş ve bir testin her çalıştırmada karşılaştırdığı referans kaydıdır. NextPDF, kimsenin amaçlamadığı değişiklikleri yakalamak için altın dosyaları kullanır: farklı biçimde sıkıştırılmış bir akış, yeri değişmiş bir paragraf veya kaymış bir koordinat. Bu sayfa, bunun nasıl çalıştığını ve bir altın dosyanın kimsenin okumadığı eski bir referansa dönüşmek yerine nasıl güvenilir kaldığını açıklar.

Bu neden önemli

PDF üretimi, birçok noktasında sessiz kaymalar oluşabilen uzun bir işlem hattıdır. “Hiçbir şeyi değiştirmeyen” bir yeniden düzenleme, operatörleri sessizce yeniden sıralayabilir, bir dönüşüm matrisini değiştirebilir veya bir tablo hücresini çok küçük bir miktarda kaydırabilir. Birim testleri bunu nadiren yakalar: kontrol etmeyi düşündüğünüz bir değer üzerinde doğrulama yaparlar, düşünmediğiniz binlerce bayt üzerinde değil. Yapı tabanlı ve belirtim (specification) tabanlı teknikler farklı hataları tespit eder ve hiçbiri diğerini kapsamaz (ISO/IEC/IEEE 29119-4, Annex A). Altın dosya, tek bir doğrulamayı değil çıktının tamamını sabitleyen, örnekle belirtim (specification-by-example) yöntemidir.

Risk her iki yönde de işler. Aşırı katı bir altın dosya, her zararsız değişiklikte başarısız olur ve hiçbir şey kanıtlamaz hâle gelene kadar körü körüne yeniden onaylanır. Aşırı gevşek bir altın dosya ise gerçek gerilemelerin (regresyonların) geçmesine izin verir. Asıl iş, bu dengeyi doğru kurmaktır.

Kısa özeti

Bir altın dosya, doğru olduğu bilinen motor davranışından üretilen, depoya işlenen ve sabitlenmiş bir referans çıktısıdır.
Bir altın testi, çıktıyı yeniden üretir ve onu sabitlenmiş referansla karşılaştırır; herhangi bir fark testi başarısız kılar ve insan kararı gerektirir.
NextPDF, anlamlı ama kararlı düzeyde karşılaştırma yapar: ham baytları değil, çıkarılan metni ve normalleştirilmiş yapısal operatörleri; çünkü ham baytlar, gerileme olmayan gürültüler (zaman damgaları, alt küme sıralaması, sıkıştırma) taşır.
Bir altın dosyayı güncellemek, açık bir GOLDEN_UPDATE anahtarının ardında yürütülen kasıtlı ve gözden geçirilmiş bir eylemdir; asla “değişen ne varsa kabul et” şeklinde otomatik bir işlem değildir.
Altın dosya, anlık görüntü (snapshot) ve karakterizasyon testinden belirleyici bir noktada ayrılır: bir altın dosya asla otomatik güncellenmez.

NextPDF buna nasıl yaklaşır

Motorun altın dosya altyapısı, bayt düzeyinde karşılaştırma yerine açık bir iki katmanlı fark (diff) kullanır:

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

Bir NextPDF altın dosya karşılaştırması nasıl çalışır: PDF'yi üretin, anlamlı katmanları (önce metin, ardından normalleştirilmiş yapısal operatörler) çıkarın, her birini sabitlenmiş referansla karşılaştırın ve herhangi bir farkta insan tarafından okunabilir bir raporla başarısız olun.

Bilinçli olarak karşılaştırmadığı şey, karşılaştırdığı şey kadar önemlidir. Ham bayt çıktısı kapsam dışı bırakılır; çünkü zaman damgaları, yazı tipi alt küme sıralaması ve akış sıkıştırması, çıktıyı daha doğru hâle getirmeden kırılgan kılar. Piksel düzeyinde görüntü farkı bu katmanda kapsam dışında bırakılır; çünkü harici bir işleyici (renderer) gerektirir ve ortam değişkenliğini içeri taşır. Kayan noktalı koordinatlar sabit bir hassasiyete normalleştirilir; böylece anlamsız yuvarlama gürültüsü, bir gerileme gibi görünmez. Davranışı test eden bir altın dosya ile geçici ortam gürültüsünü test eden bir altın dosya arasındaki fark budur.

Bu tercih, aynı zamanda sayfanın yeniden üretilebilirlik profilini de adlandırır: yapısal. NextPDF üç profili belgeler — bit düzeyinde (bitwise) (baytlar tam olarak yeniden üretilir), yapısal (structural) (nesne grafiği ve operatör dizisi yeniden üretilir, zararsız bayt düzeyinde değişkenliğe izin verilir) ve anlamsal (semantic) (anlam yeniden üretilir). Bu katmandaki altın testleri, yapıları gereği yapısal profili doğrular. Bu yüzden referansları, bir sıkıştırma kütüphanesinin sürüm yükseltmesinden etkilenmeden geçer ama yine de yeri değişmiş bir tabloda başarısız olur.

Kanıtın söyledikleri

Evidence: Test-backed İki katmanlı karşılaştırma (metin çıkarımı, ardından normalleştirilmiş yapısal operatör karşılaştırması), motorun belgelenmiş altın dosya yöntemidir; ham bayt, görüntü farkı ve tam kayan noktalı karşılaştırma ise yukarıdaki nedenlerle açıkça kapsam dışıdır. Altın dosya paketi, anlık görüntü ve karakterizasyon paketlerinden farklı, tanımlı ve ayrı çalıştırılabilen bir test paketidir.

Evidence: Test-backed Dürüstlük mekanizması somuttur: altın dosya referansları elle yazılmış değil, üretilmiş yapılardır. Bunların üzerine yazma işlemi, açık bir GOLDEN_UPDATE ortam anahtarının ardına alınmıştır; bu anahtar nadir ve her zaman gözden geçirilen bir işlem olarak belgelenmiştir. Buna karşılık, motordaki anlık görüntü testlerinin referansları ilk çalıştırmada yeniden üretilir ve kayma bir güncelleme bayrağı aracılığıyla kabul edilir. Karakterizasyon testleri ise eski (legacy) davranışın doğru olduğunu iddia etmeden sabitler. Bu üçü, bilinçli olarak farklı araçlardır.

Evidence: Standard-backed Altın dosya, bir örnekle belirtimdir (specification-by-example). Spec: ISO/IEC/IEEE 29119-4, Annex A belirtim tabanlı ve yapı tabanlı tekniklerin farklı hata sınıflarını yakaladığını ve bir stratejinin bunları birleştirmesi gerektiğini belirtir. Bu yüzden altın dosyalar, test piramidindeki birim ve yapısal testlerin yerine değil, onların yanında yer alır.

Uygulamalı örnek

Bir altın testi mekanik olarak basittir; disiplin, onun etrafındaki iş akışındadır:

<?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.

Örnek, sürecin kendisidir. Test kodu yalnızca farkı hesaplar. Altın dosyayı güvenilir kılan şey, değişmiş bir referansın, motoru değiştiren aynı değişiklik içinde çıktı olarak gözden geçirilmesidir.

Yaygın yanılgı

En yaygın hata, altın dosya testini bayt bayt test olarak görmektir. NextPDF’in altın dosyaları, dosyanın baytları değildir; çıkarılan metni ve normalleştirilmiş yapısal operatörleridir. Ham baytları doğrulamak; yeni bir zlib sürümünde, farklı bir alt küme etiketinde veya yeniden üretilmiş bir zaman damgasında başarısız olur ve bunların hiçbiri gerileme değildir. Test, bir hafta içinde yeniden onaylana onaylana işe yaramaz hâle gelirdi. (Baytların gerçekten tam olarak yeniden üretilmesi gereken durumlarda, bu bir altın dosya değil, ayrı ve daha katı olan bit düzeyinde yeniden üretilebilirlik profilidir.)

İkinci hata, yeşil bir altın dosya paketinin doğruluğu kanıtladığını varsaymaktır. Yalnızca değişmediğini kanıtlar. Hatalı bir çıktıdan üretilen bir altın dosya, o hatayı sadakatle korur. Altın dosyalar, doğru olduğu bilinen bir temel çizgiye göre oluşan gerilemelere karşı koruma sağlar; temel çizginin doğru olduğunu kanıtlamazlar. Birim, yapısal ve uygunluk (conformance) katmanları bunun içindir.

Sınırlar ve kapsam

Bir altın testi tam olarak tek bir soruyu yanıtlar: çıktı, sabitlenmiş referanstan değişti mi. Referansın doğru olup olmadığını hiçbir zaman söylemez. Ayrıca performansı, uygunluğu veya güvenliği de ölçmez. Bunlar başka katmanların işidir. Fikstür koleksiyonunun boyutu, paketin geçme oranı ve herhangi bir kapsam değeri; sürekli tümleştirme (continuous-integration) yapıtlarından üretilen ve derlemeyle birlikte yayımlanan canlı kalite sinyalleridir. Burada eskiyebilecekleri için bilinçli olarak belirtilmemişlerdir.

Tam dizin yerleşimi, karşılaştırıcının iç yapısı ve güncelleme anahtarı, motorun test altyapısına aittir ve zaman içinde gelişebilir. Bu açıklamayla herhangi bir uyuşmazlık olması durumunda yetkili kaynak, test yapılandırmasıdır. Bu sayfa, başka herhangi bir kütüphanenin anlık görüntü veya altın dosya araçları hakkında hiçbir iddiada bulunmaz.

İlgili belgeler

NextPDF test piramidi — altın dosya katmanının beş katman arasında nerede durduğu ve benzersiz olarak neyi kanıtladığı.
Mutasyon testi açıklaması — NextPDF’in, altın dosyalar dâhil testlerinin gerçekten hataları tespit edip etmediğini nasıl kontrol ettiği.
Her yerde katı tipler — herhangi bir altın dosya çalışmadan önce bir kusur sınıfını ortadan kaldıran statik analiz.

Sözlük

Altın dosya — doğru olduğu bilinen motor davranışından üretilen, depoya işlenen ve bir testin her çalıştırmada karşılaştırdığı, sabitlenmiş bir referans çıktısı. Asla otomatik güncellenmez.
İki katmanlı fark — NextPDF’in altın dosya karşılaştırması: ham baytlar yerine, çıkarılan metin (Katman 1) ile normalleştirilmiş yapısal operatörler (Katman 2).
Anlık görüntü testi — referansın ilk çalıştırmada yeniden üretildiği ve kaymanın bir güncelleme bayrağı aracılığıyla kabul edildiği, ilişkili ama farklı bir teknik.
Karakterizasyon testi — genellikle bir yeniden düzenlemeyi güvenli kılmak amacıyla, mevcut davranışın doğru olduğunu öne sürmeden sabitleyen bir test.
Yeniden üretilebilirlik profili — çıktının yeniden üretilmesi gereken düzey: bit düzeyinde (baytların tamamı), yapısal (nesne grafiği ve operatör dizisi, zararsız bayt değişkenliğine izin verilir) veya anlamsal (anlam). Buradaki altın testleri, yapısal profili doğrular.
GOLDEN_UPDATE — altın dosya referanslarının üzerine yazmaya yetki veren açık ortam anahtarı; nadir ve gözden geçirilen bir işlem.