ข้ามไปยังเนื้อหา
NextPDF

พีระมิดการทดสอบของ NextPDF

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

ภาพรวมโดยสังเขป

หัวข้อที่มีชื่อว่า “ภาพรวมโดยสังเขป”

NextPDF ไม่ได้พึ่งการทดสอบเพียงชนิดเดียว กลยุทธ์การทดสอบนี้แบ่งเป็นห้าระดับ และแต่ละระดับตอบคำถามคนละข้อเกี่ยวกับ engine เหตุผลคือ PDF อาจผ่าน unit tests ได้ แต่ยังเป็นไฟล์ที่เสียหายเชิงโครงสร้างบนดิสก์อยู่ดี หน้านี้ระบุชื่อระดับทั้งห้าและสิ่งที่แต่ละระดับมีหน้าที่พิสูจน์

เหตุใดเรื่องนี้จึงสำคัญ

หัวข้อที่มีชื่อว่า “เหตุใดเรื่องนี้จึงสำคัญ”

PDF engine มีพื้นที่ที่อาจล้มเหลวได้กว้างผิดปกติ เส้นทางของโค้ดเดียวกันอาจถูกต้องในเชิงฟังก์ชันและถูกต้องในฐานะสตรีมไบต์ แต่ยังสร้างไฟล์ที่โปรแกรมอ่านซึ่งสอดคล้องตามมาตรฐานปฏิเสธได้ เส้นทางเดียวกันนี้ยังอาจสร้างไฟล์ที่เรนเดอร์ผิดเพียงเล็กน้อยเฉพาะตรงจุดขึ้นหน้าใหม่ได้ด้วย หากทดสอบ engine ที่ระดับความละเอียดเพียงระดับเดียว ความมั่นใจก็จะจำกัดอยู่ที่ระดับความละเอียดนั้นเท่านั้น ไม่มากไปกว่านั้น

เอกสารมาตรฐานต่าง ๆ ระบุเรื่องนี้ไว้อย่างชัดเจน เทคนิคการออกแบบการทดสอบแบบอิงข้อกำหนดและแบบอิงโครงสร้างไม่ได้ครอบคลุมแทนกัน และแนวทางที่แนะนำคือให้กลยุทธ์การทดสอบใช้เกณฑ์มากกว่าหนึ่งเกณฑ์ โดยอย่างน้อยต้องมีเกณฑ์เชิงฟังก์ชันหนึ่งเกณฑ์และเกณฑ์เชิงโครงสร้างหนึ่งเกณฑ์ (ISO/IEC/IEEE 29119-4, ภาคผนวก A) ระดับเดียวไม่ใช่กลยุทธ์ที่ดีในเวอร์ชันย่อส่วน แต่เป็นกลยุทธ์คนละแบบ และเป็นกลยุทธ์ที่ไม่สมบูรณ์

ฉบับย่อ

หัวข้อที่มีชื่อว่า “ฉบับย่อ”

NextPDF จัดระเบียบการทดสอบเป็นห้าระดับ จากฐานขึ้นไปถึงยอด ดังนี้

  1. Unit — คลาสหรือฟังก์ชันเดียว แบบแยกเดี่ยว เป็นฐานกว้าง
  2. Integration — units ที่ทำงานร่วมกันข้ามขอบเขตโมดูล
  3. Structural — object graph ของ PDF ที่สร้างออกมา รวมถึงตาราง cross-reference และ trailer มีรูปแบบถูกต้องและสอดคล้องตามมาตรฐาน
  4. Visual — หน้า PDF ที่เรนเดอร์ออกมาตรงกับข้อมูลอ้างอิงที่ได้รับการอนุมัติภายในค่าความคลาดเคลื่อนที่ระบุไว้
  5. Golden — fixtures แบบ end-to-end ที่ตรึงไว้ ซึ่งจับการเปลี่ยนแปลงที่ไม่ได้ตั้งใจในเอาต์พุตสุดท้ายและทำหน้าที่เป็นยอด

แต่ละระดับพิสูจน์สิ่งที่ระดับต่ำกว่าไม่สามารถพิสูจน์ได้ ไม่มีระดับใดเป็นเพียงส่วนประกอบตกแต่ง รูปทรงพีระมิดสื่อถึง ปริมาณ คือ unit tests ราคาถูกจำนวนมาก และการทดสอบแบบ end-to-end ที่มีต้นทุนสูงจำนวนน้อยกว่า ไม่ใช่ลำดับความสำคัญ

แนวทางที่ NextPDF ใช้

หัวข้อที่มีชื่อว่า “แนวทางที่ NextPDF ใช้”

ระดับเหล่านี้มีอยู่จริงในโครงสร้างโปรเจ็กต์ ไม่ใช่เป็นเพียงอุดมคติ การกำหนดค่า PHPUnit ของรีโพซิทอรีประกาศแต่ละระดับเป็น test suite ที่มีชื่อ และจับคู่แบบหนึ่งต่อหนึ่งกับไดเรกทอรี ดังนั้นแต่ละระดับจึงเป็นเป้าหมายที่สั่งให้ runner ทำงานได้จริง ไม่ใช่ป้ายกำกับบนสไลด์ suites ที่วิศวกรอาวุโสจะคุ้นเคย ได้แก่ Unit, Integration, Golden, Snapshot, Reproducibility, Conformance, Standards และ Performance โดยแต่ละ suite มีโปรไฟล์การรันของตนเอง (การแยกเดี่ยว จังหวะการรัน และว่าจะรันโดยค่าเริ่มต้นในระบบ continuous integration หรือไม่)

การแยกส่วนนี้เป็นความตั้งใจ ระดับฐานที่รวดเร็ว (Unit) รันทุกครั้งที่มีการเปลี่ยนแปลง โดยมีงบเวลาหนึ่งวินาทีต่อการทดสอบหนึ่งรายการ ระดับที่ช้ากว่าและไวต่อสภาพแวดล้อม เช่น การเรนเดอร์เชิงภาพ การตรวจสอบความสอดคล้องแบบเต็มรูปแบบ และประสิทธิภาพ จะรันแบบเลือกเปิดเองหรือรันรายคืน วิธีนี้ช่วยให้เส้นทางหลักรวดเร็วและให้ผลคงที่ โดยไม่ละทิ้งการตรวจสอบเชิงลึก การกำหนดชนิดข้อมูลอย่างเข้มงวดเป็นรากฐานรองรับทั้งสแตก engine รันการวิเคราะห์ในระดับ Spec: PHPStan, Level 10 โดยล็อกงบประมาณข้อผิดพลาดไว้ที่ศูนย์ ดังนั้นข้อบกพร่องจำนวนมากจึงไม่เคยไปถึงขั้นการทดสอบเลย

  1. Tier 1 of 5 Unit Isolated behaviour of a single class or function; the broad base.
  2. Tier 2 of 5 Integration Collaborating units across a module boundary.
  3. Tier 3 of 5 Structural The emitted PDF object/xref structure is well-formed and conformant.
  4. Tier 4 of 5 Visual Rendered output matches an approved reference within tolerance.
  5. Tier 5 of 5 Golden End-to-end byte/lossless fixtures pinned as the contract; the apex.
ระดับการทดสอบทั้งห้าของ NextPDF จากฐานขึ้นไปถึงยอด Unit คือฐานที่กว้างและรวดเร็ว แต่ละระดับที่สูงขึ้นไปพิสูจน์คุณสมบัติที่ระดับต่ำกว่าไม่สามารถพิสูจน์ได้ ไปจนถึง golden fixtures แบบ end-to-end ที่ยอด ความกว้างเป็นเพียงสัญญาณบอกปริมาณเท่านั้น ไม่ใช่การจัดอันดับความสำคัญ

หลักฐานบอกอะไร

หัวข้อที่มีชื่อว่า “หลักฐานบอกอะไร”

Evidence: Test-backed suites ทั้งห้ามีอยู่จริงในรูปของ PHPUnit test suites ที่ประกาศไว้ในการกำหนดค่าของ engine โดยแต่ละ suite ผูกกับ ไดเรกทอรีและโปรไฟล์การรันของตนเอง คำศัพท์เรื่องระดับที่ใช้ในหน้านี้เป็น คำศัพท์ชุดเดียวกับที่โครงสร้างพื้นฐานการทดสอบใช้

Evidence: Standard-backed เหตุผลที่ต้องมีระดับ มากกว่าหนึ่ง ระดับ มีรากฐานอยู่ใน Spec: ISO/IEC/IEEE 29119-4, Annex A คือ เกณฑ์ coverage ต่าง ๆ ไม่ได้สัมพันธ์กันทั้งหมด และกลยุทธ์ที่แนะนำคือการ ผสมผสานเทคนิคเชิงฟังก์ชันและเชิงโครงสร้างเข้าด้วยกัน ที่สำคัญ ภาคผนวกเดียวกันนี้ ระบุว่าลำดับการครอบคลุม (subsumes) ระหว่างเกณฑ์ coverage ไม่ได้บ่งชี้ถึง ความสามารถในการเปิดเผยข้อบกพร่อง ซึ่งก็คือ ประสิทธิผลของการทดสอบ (ISO/IEC/IEEE 29119-4, §C.2.4) “coverage มากขึ้น” ไม่ใช่ข้อกล่าวอ้างเดียวกัน กับ “การทดสอบที่ดีกว่า”

Evidence: Standard-backed การเลือกว่าจะพิสูจน์คุณสมบัติ ใด นั้นจับคู่กับคุณลักษณะคุณภาพผลิตภัณฑ์ของ Spec: ISO/IEC 25010 ได้แก่ ความถูกต้องเชิงฟังก์ชัน (unit, integration) และ คุณสมบัติระดับไฟล์ที่ทำให้ PDF สามารถใช้งานต่อในขั้นถัดไปได้จริง (structural, visual, golden) แบบจำลองคุณภาพระบุไว้อย่างชัดเจนว่าคุณลักษณะที่แตกต่างกัน มีความสำคัญในบริบทการใช้งานที่แตกต่างกัน

ตัวอย่างการใช้งานจริง

หัวข้อที่มีชื่อว่า “ตัวอย่างการใช้งานจริง”

ระดับเหล่านี้เรียกใช้ได้จากสคริปต์ของ engine เอง การเปลี่ยนแปลง formatter เพียงตัวเดียวจะได้รับการตรวจสอบที่ระดับฐาน ส่วนการเปลี่ยนแปลง document facade จะได้รับการตรวจสอบข้ามหลายระดับ ดังนี้

<?php


declare(strict_types=1);


// Tier 1 — Unit: one unit, isolated, fast.
// composer test:unit         → phpunit --testsuite Unit


// Tier 2 — Integration: collaborating units across a boundary.
// composer test:integration  → phpunit --testsuite Integration


// Tier 3 — Structural: the emitted PDF object graph is well-formed.
// vendor/bin/phpunit --testsuite Conformance


// Tier 4/5 — Visual + Golden: rendered/serialized output vs a pinned
// reference (golden is byte/structure-pinned, never auto-updated).
// vendor/bin/phpunit --testsuite Golden


// A change to the document facade touches every API, so the routing
// guidance escalates it from "unit only" to the full unit + integration
// surface — the tier you run is a function of blast radius, not habit.

ประเด็นสำคัญของตัวอย่างนี้คือตรรกะการกำหนดเส้นทาง ไม่ใช่ตัวคำสั่ง ระดับที่เลือกให้รันขึ้นอยู่กับสิ่งที่การเปลี่ยนแปลงอาจทำให้เสียหายได้ โครงสร้างพื้นฐานทำให้แต่ละระดับเป็นเป้าหมายชั้นหนึ่งที่สามารถรันแยกได้

ความเข้าใจผิดที่พบบ่อย

หัวข้อที่มีชื่อว่า “ความเข้าใจผิดที่พบบ่อย”

พีระมิดมักถูกตีความว่าเป็น การจัดอันดับ คือ unit tests อยู่ล่างสุดเพราะสำคัญน้อยที่สุด และการทดสอบแบบ end-to-end อยู่บนสุดเพราะสำคัญที่สุด (หรือกลับกัน) แต่ไม่ใช่ทั้งสองอย่าง แกนแนวตั้งสื่อถึงต้นทุนและปริมาณโดยคร่าว ๆ คือ unit tests ที่รวดเร็วและราคาถูกจำนวนมากซึ่งก่อเป็นฐานกว้าง และการทดสอบที่ช้ากว่าแต่มีความเที่ยงตรงสูงกว่าซึ่งมีจำนวนน้อยลงเรื่อย ๆ อยู่เหนือขึ้นไป golden tests ไม่ได้ “ดีกว่า” unit tests golden tests จับความล้มเหลวคนละแบบ ด้วยความเร็วที่ช้ากว่าและต้นทุนที่สูงกว่า และเป็นตัวแทนที่ไม่ดีสำหรับการตรวจสอบที่รวดเร็วนับพันรายการที่อยู่ด้านล่าง

ความเข้าใจผิดประการที่สองคือ ตัวเลข coverage สูงหมายความว่าพีระมิดมั่นคง ซึ่งไม่เป็นเช่นนั้น Coverage วัดการเรียกทำงาน ไม่ใช่การตรวจจับ มาตรฐานต่าง ๆ ปฏิเสธอย่างชัดเจนที่จะถือว่าลำดับของ coverage เทียบเท่ากับความสามารถในการค้นหาข้อบกพร่อง ช่องว่างนี้คือสิ่งที่ mutation testing มีไว้เพื่อเปิดเผยโดยเฉพาะ

ข้อจำกัดและขอบเขต

หัวข้อที่มีชื่อว่า “ข้อจำกัดและขอบเขต”

หน้านี้อธิบาย รูปแบบและเจตนา ของกลยุทธ์ ไม่ใช่ผลลัพธ์ปัจจุบัน จำนวนการทดสอบ เปอร์เซ็นต์ coverage และคะแนน mutation จงใจไม่ระบุไว้ที่นี่ ค่าเหล่านี้เป็นสัญญาณคุณภาพที่อัปเดตอยู่เสมอและสร้างจาก artifacts ของ continuous integration ตัวเลขปัจจุบันเผยแพร่พร้อมกับการ build หากตรึงค่าเหล่านี้ไว้ในเนื้อความ ค่าเหล่านี้จะค่อย ๆ ล้าสมัยไปอย่างเงียบ ๆ ตัวเลขเดียวที่ระบุไว้ คือ PHPStan Level 10 เป็นข้อเท็จจริงด้านการกำหนดค่าที่คงที่ ซึ่งตรวจสอบได้ในการกำหนดค่าการวิเคราะห์แบบสถิตของ engine ไม่ใช่ค่าที่ได้จากการวัด

ส่วน ชื่อ ของระดับเป็นคำศัพท์เชิงสถาปัตยกรรมที่คงที่ รายการ suites ที่แน่นอนและโปรไฟล์การรันของแต่ละ suite จะพัฒนาไปพร้อมกับ engine และเป็นความรับผิดชอบของการกำหนดค่าการทดสอบ ซึ่งถือเป็นแหล่งอ้างอิงที่เชื่อถือได้หากเกิดความขัดแย้งกับคำอธิบายนี้ หน้านี้ไม่ได้ยืนยันอัตราการผ่านที่เฉพาะเจาะจงใด ๆ และไม่ได้เปรียบเทียบกับกลยุทธ์การทดสอบของไลบรารีอื่นใด

เอกสารที่เกี่ยวข้อง

หัวข้อที่มีชื่อว่า “เอกสารที่เกี่ยวข้อง”
  • การทดสอบ golden-file — วิธีที่ระดับยอดตรึงเอาต์พุตอ้างอิงและทำให้การเปรียบเทียบยังตรงไปตรงมา
  • Mutation testing อธิบายแบบเข้าใจง่าย — เหตุใดตัวเลข coverage จึงไม่พิสูจน์ว่าการทดสอบในระดับเหล่านี้ทำงานได้จริง
  • Strict types ทุกที่ — วิธีที่ PHPStan Level 10 กำจัดข้อบกพร่องกลุ่มหนึ่งก่อนที่ระดับใด ๆ จะเริ่มรัน

อภิธานศัพท์

หัวข้อที่มีชื่อว่า “อภิธานศัพท์”
  • Test tier — ระดับหนึ่งในกลยุทธ์ที่พิสูจน์คุณสมบัติประเภทหนึ่ง (เช่น พฤติกรรมระดับ unit หรือความถูกต้องเชิงโครงสร้าง) NextPDF ใช้ห้าระดับ
  • Structural test — การตรวจสอบว่า object graph ของ PDF ที่สร้างออกมา รวมถึงตาราง cross-reference และ trailer มีรูปแบบถูกต้องและสอดคล้องตามมาตรฐาน ตรงข้ามกับการตรวจสอบเพียงค่าที่คืนกลับมา
  • Visual test — การตรวจสอบว่าหน้า PDF ที่เรนเดอร์ออกมาตรงกับภาพอ้างอิงที่ได้รับการอนุมัติภายในค่าความคลาดเคลื่อนที่ระบุไว้
  • Golden test — การตรวจสอบแบบ end-to-end เทียบกับเอาต์พุตอ้างอิงที่ตรึงไว้ ซึ่งไม่เคยอัปเดตโดยอัตโนมัติ เป็นสัญญาที่รับรองว่า “เอาต์พุตไม่เปลี่ยนแปลง”
  • Test effectiveness — ความสามารถของชุดการทดสอบในการเปิดเผยข้อบกพร่อง ซึ่ง ISO/IEC/IEEE 29119-4 แยกออกจาก coverage หมายเหตุเกี่ยวกับตัวย่อ: MSI (Mutation Score Indicator) นิยามไว้ในหน้า mutation testing ของเอกสารนี้
  • PHPStan Level 10 — ระดับการวิเคราะห์แบบสถิตที่เข้มงวดที่สุด NextPDF รันระดับนี้โดยล็อกงบประมาณข้อผิดพลาดไว้ที่ศูนย์