หากคุณมีไฟล์ OpenAPI แต่บริการที่ใช้งานอยู่ค่อยๆ ห่างเหินจากมัน Specmatic ถูกสร้างขึ้นมาเพื่อแก้ปัญหานี้โดยเฉพาะ โดยจะถือว่าสเปคของคุณเป็นสัญญาที่สามารถนำไปปฏิบัติได้ จากนั้นจะทดสอบบริการจริงเทียบกับสเปคนั้น และรันสเปคเดียวกันนั้นในฐานะ stub อัจฉริยะ คู่มือนี้จะอธิบายว่า Specmatic ทำอะไร การทดสอบสัญญา (contract testing) แตกต่างจากการทดสอบตามตัวอย่าง (example-based testing) อย่างไร และเครื่องมือนี้เหมาะกับสถานการณ์ใด พร้อมทั้งเปรียบเทียบกับวิธีการแพลตฟอร์มที่ครอบคลุมกว่า เช่น การทดสอบสัญญา API ของ Apidog สำหรับรูปแบบสเปคที่เป็นพื้นฐานของทั้งหมดนี้ OpenAPI Specification คือแหล่งข้อมูลที่เป็นความจริงที่ Specmatic อ่านจาก
Specmatic คืออะไร
Specmatic เป็นเครื่องมือโอเพนซอร์สสำหรับการพัฒนาแบบ contract-driven แนวคิดหลักสั้นๆ คือ: สเปค API ของคุณคือสัญญา และ Specmatic ทำให้สัญญานั้นสามารถนำไปปฏิบัติได้ เพียงแค่ชี้ไปยังไฟล์ OpenAPI มันก็สามารถทำงานสองอย่างที่เสริมกันได้
- รันสเปคเป็นชุดทดสอบกับบริการที่กำลังทำงานอยู่ ตรวจสอบว่าบริการนั้นปฏิบัติตามทุก path, status code และ schema ที่ระบุในสเปค
- รันสเปคเป็น stub server เพื่อให้ผู้บริโภคสามารถพัฒนาโดยใช้ mock ที่ตอบสนองตรงตามที่สัญญาระบุไว้
งานทั้งสองอย่างอ่านจากไฟล์เดียวกัน ไม่จำเป็นต้องมี "คำนิยามการทดสอบ" และ "สเปค" แยกกันเพื่อคอยซิงค์ ซึ่งนี่คือประเด็นสำคัญ Specmatic ยังรองรับมากกว่า OpenAPI เวอร์ชัน 2.0 ได้เพิ่ม GraphQL และ gRPC และยังรองรับ AsyncAPI สำหรับสัญญาเหตุการณ์แบบ Kafka รวมถึงรูปแบบอื่นๆ เช่น WSDL และ Avro อย่างไรก็ตาม สำหรับทีมส่วนใหญ่ จุดเริ่มต้นคือไฟล์ OpenAPI YAML หรือ JSON ธรรมดา
คุณสามารถรันได้จาก command line หรืออิมเมจ Docker ทำให้สามารถรวมเข้ากับ CI ได้อย่างง่ายดาย บริษัทที่อยู่เบื้องหลังมีส่วนเสริมเชิงพาณิชย์ให้บริการ แต่เอนจินการทำงานหลักของสัญญาเป็นแบบโอเพนซอร์สและใช้งานได้ฟรี
การทดสอบสัญญา (Contract testing) vs การทดสอบตามตัวอย่าง (Example testing)
นี่คือความแตกต่างที่ทำให้คนส่วนใหญ่สับสน ดังนั้นจึงควรทำความเข้าใจให้ชัดเจน
การทดสอบตามตัวอย่าง (Example-based testing) คือสิ่งที่คุณทำในไคลเอนต์ API ส่วนใหญ่ คุณเขียนคำขอ จากนั้นยืนยันการตอบกลับที่คุณได้รับ อาจตรวจสอบสถานะโค้ดและข้อมูลบางฟิลด์ การทดสอบแต่ละครั้งเป็นตัวอย่างที่เขียนขึ้นด้วยมือ หากสเปคของคุณมี 40 endpoints คุณจะต้องเขียนและดูแลตัวอย่างจำนวนมาก และอาจมีช่องโหว่ที่มองข้ามได้ง่าย
การทดสอบสัญญา (Contract testing) พลิกรูปแบบนี้ แทนที่จะยืนยันจากตัวอย่างเฉพาะ คุณยืนยันว่าบริการตรงตามสัญญา Specmatic อ่าน schema และสร้างการทดสอบจากมัน มันตรวจสอบว่าการตอบกลับเป็นไปตามประเภทที่ประกาศไว้, มีฟิลด์ที่จำเป็นอยู่ครบ, สถานะโค้ดตรงกัน และบริการปฏิเสธคำขอที่ไม่ถูกต้องตามที่สเปคระบุ คุณไม่ต้องเขียนคำยืนยันทีละรายการ สเปคคือคำยืนยันนั้นเอง
| ประเด็น | การทดสอบตามตัวอย่าง | การทดสอบสัญญาด้วย Specmatic |
|---|---|---|
| แหล่งที่มาของความจริง | กรณีทดสอบที่เขียนด้วยมือ | ตัวสเปค OpenAPI เอง |
| สิ่งที่คุณดูแลรักษา | แต่ละคำขอและการยืนยัน | สเปคที่คุณเก็บไว้อยู่แล้ว |
| ความครอบคลุม | เฉพาะสิ่งที่คุณจำได้ว่าต้องเขียน | ทุกการดำเนินการที่สเปคประกาศไว้ |
| การตรวจจับความคลาดเคลื่อน | ด้วยตนเอง | อัตโนมัติเมื่อสเปคเปลี่ยนแปลง |
| ความล้มเหลวทั่วไป | ตัวอย่างเฉพาะเจาะจงใช้งานไม่ได้ | บริการไม่ตรงกับสัญญาอีกต่อไป |
มีอีกประเด็นหนึ่งที่ควรกล่าวถึง การทดสอบสัญญามีหลายรูปแบบ และ Specmatic อยู่ในรูปแบบที่เฉพาะเจาะจง การทดสอบสัญญาแบบ consumer-driven สไตล์ Pact นั้น ผู้บริโภคจะเผยแพร่ความคาดหวังของตนไปยัง broker และผู้ให้บริการจะตรวจสอบกับสิ่งเหล่านั้น แต่ Specmatic ทำการทดสอบแบบ contract-driven แทน: สเปคคือสัญญาเดียวที่ทั้งสองฝ่ายเห็นชอบ และ Specmatic จะตรวจสอบผู้ให้บริการเทียบกับสัญญานั้น และสร้าง stub สำหรับผู้บริโภค มันไม่ใช่ Pact broker และไม่ได้จัดการ pact ที่ผู้บริโภคเผยแพร่ หากคุณต้องการภาพรวมที่กว้างขึ้น โปรดดูภาพรวมของ เครื่องมือทดสอบสัญญาและสร้าง mock API นี้
วิธีการทำงานของ Specmatic
คุณสามารถติดตั้ง CLI ได้โดยตรง หรือดึงอิมเมจ Docker มาใช้งาน Docker เป็นทางเลือกที่นิยมใน CI เพราะช่วยหลีกเลี่ยงการตั้งค่ารันไทม์ในเครื่อง
การรันการทดสอบสัญญา
คำสั่งทดสอบจะชี้ Specmatic ไปยังสเปคและบริการที่กำลังทำงานอยู่ การรันในเครื่องแบบพื้นฐานจะมีลักษณะดังนี้
# CLI แบบ Native
specmatic test api.yaml --testBaseURL=http://localhost:8080
# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
Specmatic อ่าน api.yaml สร้างคำขอสำหรับการดำเนินการที่อธิบายไว้ ส่งไปยัง URL พื้นฐาน และตรวจสอบการตอบกลับทุกรายการเทียบกับ schema การทดสอบที่ไม่ผ่านหมายความว่าบริการกับสัญญามีความไม่ตรงกัน คุณแก้ไขอย่างใดอย่างหนึ่ง นั่นคือขั้นตอนการทำงาน
การรันสเปคในฐานะ stub
Stub server เป็นอีกครึ่งหนึ่ง เมื่อคุณเริ่มมัน Specmatic จะตอบสนองที่ตรงกับสัญญา เพื่อให้ front-end หรือบริการดาวน์สตรีมสามารถพัฒนาโดยใช้มันได้ก่อนที่ backend จริงจะถูกสร้างขึ้น
specmatic stub api.yaml --port=9000
โดยค่าเริ่มต้น มันจะสร้างการตอบกลับที่ถูกต้องตาม schema ได้ทันที คุณยังสามารถบันทึกตัวอย่างที่เป็นรูปธรรมไว้ในไดเรกทอรี _examples ถัดจากสเปค และ stub จะส่งคืนสิ่งเหล่านั้นเมื่อคำขอตรงกัน สิ่งนี้ช่วยให้คุณได้ข้อมูลที่สมจริงและควบคุมได้ โดยไม่ต้องมี backend จริง หากคุณกำลังเปรียบเทียบตัวเลือก stub และ mock ในเครื่องมือต่างๆ ภาพรวมของ การทดสอบสัญญาและ mock server จะช่วยให้คุณเข้าใจบริบทของ Specmatic ได้
Specmatic ยังช่วยคุณสร้างสเปคตั้งแต่แรกได้ด้วย มันสามารถทำงานเป็น proxy อยู่หน้าบริการที่มีอยู่ จับการรับส่งข้อมูลจริง และสร้างเอกสาร OpenAPI พร้อมไฟล์ตัวอย่างจากสิ่งที่ตรวจพบ สิ่งนี้มีประโยชน์เมื่อคุณมีบริการแต่ยังไม่มีสเปคอย่างเป็นทางการ
โมเดลสเปคในฐานะสัญญาและ stub
นี่คือเหตุผลว่าทำไมการรันไฟล์เดียวเป็นทั้งการทดสอบและ stub จึงมีความสำคัญ เมื่อสเปคเป็นสัญญา ฝั่งการทดสอบและฝั่ง stub จะไม่มีทางขัดแย้งกันได้ เพราะทั้งคู่ต่างอ่านเอกสารเดียวกัน
- ทีมผู้ให้บริการรัน
specmatic testใน CI หากพวกเขามีการเปลี่ยนแปลง API โดยไม่อัปเดตสเปค การทดสอบสัญญาจะล้มเหลว - ทีมผู้บริโภครัน
specmatic stubในเครื่อง พวกเขาพัฒนาโดยใช้การตอบสนองที่รับประกันว่าจะตรงกับสัญญาเดียวกัน
ดังนั้น สเปคจึงกลายเป็นข้อตกลงที่มีชีวิต ไม่ใช่เอกสารเก่าที่ไม่มีใครเชื่อถือ นี่คือความแตกต่างระหว่าง stub และ mock ที่ซับซ้อนกว่า และคุ้มค่าที่จะทำความเข้าใจแนวคิดพื้นฐานใน การทำ API stubbing vs mocking ก่อนที่คุณจะออกแบบเวิร์กโฟลว์รอบๆ มัน
Specmatic ยังเพิ่มการตรวจสอบความเข้ากันได้แบบย้อนหลัง (backward-compatibility) คำสั่ง backward-compatibility-check จะเริ่ม stub จากสเปคเวอร์ชันใหม่ สร้างการทดสอบจากเวอร์ชันก่อนหน้า และรันการทดสอบเหล่านั้นกับ stub ใหม่ หากบางสิ่งที่เคยทำงานได้ไม่สามารถทำงานได้อีกต่อไป คุณจะทราบก่อนที่คุณจะส่งมอบงาน นั่นคือการป้องกันที่แข็งแกร่งสำหรับ microservices ที่มีการติดตั้งใช้งานอย่างอิสระ และเป็นรูปแบบหนึ่งของแนวคิดที่กว้างขึ้นซึ่งครอบคลุมอยู่ใน การทดสอบสัญญาแบบสองทิศทาง
Specmatic เหมาะกับอะไรบ้าง
Specmatic มีประโยชน์อย่างยิ่งเมื่อทีมของคุณมีเงื่อนไขเหล่านี้เป็นจริง:
- สเปค OpenAPI (หรือ AsyncAPI, GraphQL, gRPC) ของคุณเป็นของจริงและสมบูรณ์พอสมควร
- คุณมีทีมผู้ให้บริการและผู้บริโภค หรือบริการที่แยกกัน ซึ่งจำเป็นต้องทำงานร่วมกันอย่างสอดคล้อง
- คุณต้องการให้ความคลาดเคลื่อนของสเปคทำให้ build ล้มเหลวโดยอัตโนมัติ ไม่ใช่ไปตรวจพบในการรีวิว
- คุณคุ้นเคยกับเวิร์กโฟลว์ที่เน้น CLI และ CI เป็นหลัก
มันอาจจะไม่เหมาะนักหากคุณไม่ได้เก็บสเปคไว้ หากคุณต้องการพื้นที่ทำงานแบบภาพสำหรับออกแบบและสำรวจ API หรือหากคุณต้องการเครื่องมือเดียวที่จัดการการดีบักชั่วคราว เอกสารประกอบ และการทำงานร่วมกันในทีม Specmatic มุ่งเน้นไปที่เอนจินสัญญา และทำงานนั้นได้ดีเยี่ยม
การมุ่งเน้นนั้นยังเป็นจุดที่แพลตฟอร์มอย่าง Apidog มีรูปร่างที่แตกต่างออกไป Apidog เป็นแบบ schema-driven ในลักษณะเดียวกัน: มันอ่านสเปค OpenAPI ของคุณ ตรวจสอบการตอบกลับเทียบกับ schema และสร้าง mock server จาก OpenAPI schema ของคุณ โดยไม่ต้องเขียนโค้ด ความแตกต่างที่แท้จริงคือขอบเขตการทำงาน Specmatic เป็นเครื่องมือสัญญาที่คมชัดและเป็นแบบ CLI-native Apidog รวมการออกแบบ การทดสอบ การสร้าง mock และเอกสารไว้ในพื้นที่ทำงานเดียวพร้อมตัวแก้ไขแบบภาพ ทำให้สเปค การทดสอบ และ mock อยู่ร่วมกันและซิงค์กันในขณะที่คุณทำงาน Apidog ไม่ใช่ Pact broker แบบ consumer-driven contract testing ด้วย ดังนั้นหากทีมของคุณต้องการ pact broker โดยเฉพาะ เครื่องมือทั้งสองนี้ก็ไม่ตอบโจทย์นั้น
หากคุณต้องการสร้างชุดทดสอบที่สามารถรันได้โดยตรงจากสเปคภายในพื้นที่ทำงานดังกล่าว ลองดูว่า Apidog จัดการ การสร้างชุดทดสอบ API จากสเปค OpenAPI ได้อย่างไร
คำถามที่พบบ่อย
Specmatic ใช้งานได้ฟรีหรือไม่?
ใช่ เอนจินสัญญาหลักเป็นโอเพนซอร์สและใช้งานได้ฟรีจาก CLI หรือ Docker มีข้อเสนอเชิงพาณิชย์ที่เกี่ยวข้อง แต่คุณสามารถรันการทดสอบสัญญาและ stub server จากสเปค OpenAPI ได้โดยไม่ต้องเสียค่าใช้จ่าย ตรวจสอบเว็บไซต์ทางการและ GitHub สำหรับรายละเอียดปัจจุบันเกี่ยวกับระดับการชำระเงิน
Specmatic ทำงานได้เฉพาะกับ OpenAPI เท่านั้นหรือไม่?
ไม่ใช่ OpenAPI เป็นจุดเริ่มต้นที่พบบ่อยที่สุด แต่ Specmatic ยังรองรับ AsyncAPI สำหรับสัญญาแบบ event-driven รวมถึง GraphQL และ gRPC ตั้งแต่เวอร์ชัน 2.0 พร้อมด้วยรูปแบบอื่นๆ เช่น WSDL และ Avro โมเดลนี้เหมือนกันทั้งหมด: สเปคคือสัญญาที่สามารถนำไปปฏิบัติได้ หากคุณยังใหม่กับรูปแบบนี้ โปรดเริ่มต้นด้วย บทแนะนำ OpenAPI Specification นี้
Specmatic เหมือนกับ Pact หรือไม่?
ไม่เชิงทีเดียว Pact เป็นแบบ consumer-driven: ผู้บริโภคจะเผยแพร่ความคาดหวังไปยัง broker และผู้ให้บริการจะตรวจสอบกับสิ่งเหล่านั้น Specmatic เป็นแบบ contract-driven: สเปคคือสัญญาเดียวที่ใช้ร่วมกัน และ Specmatic จะตรวจสอบผู้ให้บริการเทียบกับสัญญานั้น ในขณะที่สร้าง stub ให้กับผู้บริโภค ทั้งสองวิธีช่วยลดความผิดพลาดในการผสานรวม แต่มีการจัดการสัญญาที่แตกต่างกัน
Specmatic สามารถสร้างสเปค OpenAPI ให้ฉันได้หรือไม่?
ใช่ Specmatic สามารถทำงานเป็น proxy อยู่หน้าบริการที่มีอยู่ จับการรับส่งข้อมูลคำขอและการตอบกลับจริง และสร้างเอกสาร OpenAPI พร้อมไฟล์ตัวอย่างจากมันได้ สิ่งนี้มีประโยชน์เมื่อคุณมีบริการที่ทำงานได้แต่ยังไม่มีสเปคอย่างเป็นทางการสำหรับทดสอบ
สรุป
Specmatic แก้ปัญหาเฉพาะเจาะจงและเป็นจริง: การรักษาบริการที่ทำงานอยู่ให้ซื่อสัตย์ต่อสเปค OpenAPI ที่ควรปฏิบัติตาม ด้วยการทำให้สเปคสามารถนำไปปฏิบัติได้ มันช่วยให้คุณมีการทดสอบสัญญาและ stub ที่ตรงกันจากไฟล์เดียว พร้อมกับการตรวจสอบความเข้ากันได้แบบย้อนหลังเพิ่มเข้ามา หากคุณทำงานในเทอร์มินัลและ CI และรักษาสเปคที่แข็งแกร่งไว้ มันเป็นสิ่งที่ลงตัวอย่างยิ่ง
หากคุณต้องการมีสัญญา, การทดสอบ, mock และเอกสารทั้งหมดในพื้นที่ทำงานแบบภาพเดียวที่อ่านไฟล์ OpenAPI เดียวกัน ลองใช้ Apidog มันตรวจสอบการตอบกลับเทียบกับ schema ของคุณ สร้าง mock endpoints โดยไม่ต้องเขียนโค้ด และเปลี่ยนสเปคให้เป็นชุดทดสอบที่สามารถรันได้ ดาวน์โหลด Apidog เพื่อชี้ไปยังสเปคของคุณและดูวงจรการออกแบบจนถึงการทดสอบทั้งหมดในที่เดียว