หากคุณมี OpenAPI หรือ GraphQL schema, Schemathesis สามารถเปลี่ยนมันให้เป็นกรณีทดสอบนับพันโดยที่คุณไม่ต้องเขียน assertion แม้แต่ครั้งเดียว มันจะอ่านสเปก, สร้างอินพุตที่ "ดุเดือด" และถูกต้อง, ยิงมันใส่ API ของคุณ, และรายงานว่าการตอบสนองส่วนใดที่ขัดแย้งกับสัญญา คู่มือนี้จะอธิบายว่า Schemathesis คืออะไร, วิธีการติดตั้งและรันมัน, ความหมายที่แท้จริงของการทดสอบแบบ property-based, และวิธีการทำงานร่วมกับการทดสอบเชิงฟังก์ชันและ การทดสอบสัญญา (contract testing) ใน Apidog อย่างไร
Schemathesis คืออะไร?
Schemathesis เป็นเครื่องมือ Python แบบโอเพนซอร์สที่สร้างการทดสอบ API โดยอัตโนมัติจาก schema คุณเพียงแค่ชี้มันไปยังคำจำกัดความ OpenAPI หรือ GraphQL และมันจะสร้างกรณีทดสอบจากประเภท, รูปแบบ, และข้อจำกัดที่คุณได้ประกาศไว้แล้ว มันสร้างขึ้นบน Hypothesis ซึ่งเป็นไลบรารีการทดสอบแบบ property-based สำหรับ Python และเผยแพร่ภายใต้ใบอนุญาต MIT
แนวคิดหลักนั้นง่ายมาก สเปกของคุณได้อธิบายไว้แล้วว่าคำขอและการตอบสนองที่ถูกต้องมีลักษณะอย่างไร Schemathesis ถือว่าคำอธิบายนั้นเป็นแหล่งความจริงและตรวจสอบว่า API ที่ทำงานอยู่ของคุณปฏิบัติตามนั้นจริงหรือไม่ เมื่อ API ส่งคืน 500, ส่งการตอบสนองที่ละเมิด schema ที่ประกาศไว้, หรือยอมรับอินพุตที่ควรปฏิเสธ Schemathesis จะแจ้งเตือน
คุณรันมันจากคอมมานด์ไลน์ด้วย schemathesis run (หรือชื่อย่อ st run) นอกจากนี้ยังมีการผนวกรวม Python หากคุณต้องการขับเคลื่อนมันจาก pytest แทน CLI ทีมส่วนใหญ่เริ่มต้นด้วย CLI เนื่องจากไม่จำเป็นต้องตั้งค่าอะไรเลย
ความหมายของการทดสอบแบบ Property-Based
การทดสอบ API ส่วนใหญ่เป็นแบบตัวอย่าง คุณเขียนคำขอ, คุณยืนยันการตอบสนองที่เฉพาะเจาะจง, และการทดสอบจะผ่านหรือล้มเหลวในกรณีเดียวนั้น นั่นมีประโยชน์ แต่คุณจะจับได้เฉพาะข้อบกพร่องที่คุณคิดจะเขียนการทดสอบเท่านั้น
การทดสอบแบบ property-based จะพลิกแนวทาง แทนที่จะเป็นตัวอย่างที่ตายตัวหนึ่งรายการ คุณจะอธิบายคุณสมบัติที่ควรเป็นจริงเสมอ จากนั้นให้เครื่องมือสร้างอินพุตนับร้อยเพื่อพยายามทำลายมัน สำหรับ Schemathesis คุณสมบัติคือ: "คำขอที่ถูกต้องไม่ควรทำให้เซิร์ฟเวอร์ล่มหรือสร้างการตอบสนองที่ละเมิด schema"
Schemathesis สร้างอินพุตจากข้อจำกัดในสเปกของคุณ หากฟิลด์เป็นจำนวนเต็มที่มีค่าต่ำสุด 1 มันจะลอง 1, ตัวเลขขนาดใหญ่, ค่าขอบ, และชนิดของอินพุตที่ทำให้การตรวจสอบที่ง่ายๆ พังทลาย เมื่อการทดสอบล้มเหลว Hypothesis จะย่ออินพุตให้เล็กลงจนเป็นกรณีที่เล็กที่สุดที่ยังคงสร้างข้อบกพร่องได้ เพื่อให้คุณได้รับ repro ที่เล็กที่สุดและอ่านง่าย แทนที่จะเป็น payload สุ่มขนาด 4KB
สิ่งนี้แตกต่างจากการ ทดสอบแบบ Monkey Testing ซึ่งเป็นการโยนอินพุตแบบสุ่มใส่อินเทอร์เฟซเพื่อดูว่าอะไรจะล้มเหลว การทดสอบแบบ property-based มีโครงสร้าง มันใช้ schema เพื่อสร้างอินพุตที่เป็นไปได้และตรงเป้าหมาย และมันรู้ว่าผลลัพธ์ที่ถูกต้องควรเป็นอย่างไรเพราะสเปกบอกไว้
การติดตั้งและรัน Schemathesis
Schemathesis เป็นแพ็กเกจ Python ดังนั้นคุณต้องมี Python 3 และ pip ติดตั้งได้ตามปกติ:
pip install schemathesis
คุณยังสามารถรันมันได้โดยไม่ต้องติดตั้งถาวรโดยใช้ uvx schemathesis หากคุณตั้งค่า uv ไว้ เมื่อติดตั้งแล้ว คำสั่งพื้นฐานจะชี้ไปที่ schema และ URL ฐาน:
st run http://127.0.0.1:8000/openapi.json
หาก schema ของคุณอยู่ในดิสก์แทนที่จะอยู่เบื้องหลัง URL ให้ส่งผ่านพาธไฟล์และบอก Schemathesis ว่า API จริงอยู่ที่ไหน:
st run ./openapi.yaml --url http://127.0.0.1:8000
สำหรับ API ที่มีการรับรองความถูกต้อง ให้เพิ่มส่วนหัว:
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer your-token'
Schemathesis ค้นพบทุกการดำเนินการในสเปก, สร้างกรณีทดสอบสำหรับแต่ละรายการ, และพิมพ์สรุปว่าการตรวจสอบใดผ่านและใดล้มเหลว ความล้มเหลวจะมาพร้อมกับคำขอที่ส่งไปอย่างแม่นยำ เพื่อให้คุณสามารถเล่นซ้ำได้ด้วย curl หรือในไคลเอนต์ API ใดๆ ชื่อแฟล็กและค่าเริ่มต้นจะเปลี่ยนไประหว่างเวอร์ชันหลัก ดังนั้นให้ตรวจสอบ st run --help เทียบกับเวอร์ชันที่คุณติดตั้งไว้ แทนที่จะเชื่อในบล็อกสั้นๆ รวมถึงข้อความนี้
สิ่งที่ Schemathesis ตรวจจับได้
การตรวจสอบเริ่มต้นจะมุ่งเป้าไปที่ช่องว่างระหว่างสิ่งที่สเปกของคุณสัญญาไว้และสิ่งที่เซิร์ฟเวอร์ของคุณทำ นี่คือสิ่งที่มักจะปรากฏขึ้น
| ปัญหา | ลักษณะที่ปรากฏ |
|---|---|
| ข้อผิดพลาดของเซิร์ฟเวอร์ | คำขอกระตุ้น 500 แทนที่จะเป็น 4xx ที่จัดการได้ หรือการตอบสนองที่ถูกต้อง |
| การละเมิด Schema | เนื้อหาการตอบสนองไม่ตรงกับ schema ที่คุณประกาศไว้สำหรับรหัสสถานะนั้น |
| ความไม่ตรงกันของรหัสสถานะ | API ส่งคืนรหัสสถานะที่สเปกไม่เคยบันทึกไว้ |
| Content-type ผิดเพี้ยน | ประเภทเนื้อหาการตอบสนองไม่ตรงกับที่สเปกโฆษณา |
| ข้อบกพร่องที่ต้องใช้สถานะ | การดำเนินการหนึ่งทำงานได้ด้วยตัวเอง แต่ล้มเหลวภายในเวิร์กโฟลว์แบบหลายขั้นตอนที่สมจริง |
ข้อสุดท้ายนั้นควรพิจารณาให้ละเอียด Schemathesis สามารถรันการทดสอบแบบ stateful ได้ ซึ่งมันจะเชื่อมโยงการดำเนินการเข้าด้วยกันโดยอิงตามลิงก์ในสเปกของคุณ เช่น สร้างทรัพยากร, จากนั้นเรียกใช้, จากนั้นลบ ข้อบกพร่องที่ปรากฏเฉพาะตามลำดับเท่านั้น เช่น ทรัพยากรที่รายงานสถานะผิดหลังจากอัปเดต, ยากที่จะพบด้วยการทดสอบคำขอเดียว ระยะ stateful จะขับเคลื่อนลำดับเหล่านั้นในฐานะ state machine
คุณสามารถขยายพฤติกรรมเริ่มต้นได้ด้วย hooks Hooks คือฟังก์ชัน Python ที่ช่วยให้คุณปรับแต่งการสร้างข้อมูล, เพิ่มการตรวจสอบของคุณเอง, หรือกรองว่าการดำเนินการใดบ้างที่ได้รับการทดสอบ นี่คือวิธีที่ทีมปรับ Schemathesis ให้เข้ากับ API ที่มีกระบวนการตรวจสอบสิทธิ์หรือข้อจำกัดที่ไม่ชัดเจนที่สเปกไม่สามารถแสดงออกได้
ควรใช้ Schemathesis เมื่อใด
Schemathesis มีประโยชน์เมื่อคุณมี OpenAPI หรือ GraphQL spec ที่ค่อนข้างแม่นยำและต้องการการครอบคลุมที่กว้างและราคาถูกสำหรับกรณีขอบ มันแข็งแกร่งในการค้นหาความล้มเหลวที่คุณไม่เคยคิดจะเขียนการทดสอบด้วยตนเอง: อินพุตที่ไม่ได้รับการจัดการ, รูปแบบข้อผิดพลาดที่ไม่ได้บันทึก, และความคลาดเคลื่อนของสัญญา (contract drift) ระหว่างสเปกและการใช้งาน
มันเหมาะสมอย่างยิ่งเมื่อ:
- คุณดูแลรักษา OpenAPI specification และต้องการให้มันถูกบังคับใช้กับเซิร์ฟเวอร์จริง
- คุณกังวลเกี่ยวกับ 500s ที่ไม่ได้รับการจัดการและต้องการเลเยอร์การ fuzzing ใน CI
- API ของคุณมีเวิร์กโฟลว์แบบ stateful ที่ลำดับมีความสำคัญ
- ทีมของคุณทำงานใน Python อยู่แล้วและคุ้นเคยกับ
pipและpytest
มันไม่เหมาะสมเท่าไรเมื่อสเปกของคุณไม่ละเอียดหรือล้าสมัย เนื่องจาก Schemathesis สามารถทดสอบได้เฉพาะสิ่งที่ schema อธิบายเท่านั้น ขยะเข้าขยะออก นอกจากนี้มันจะไม่มาแทนที่การทดสอบเชิงฟังก์ชันแบบตัวอย่างของคุณ การรู้ว่าปลายทางไม่เคยล่ม ไม่เหมือนกับการรู้ว่ามันส่งคืนค่าที่ถูกต้องสำหรับอินพุตที่รู้จัก คุณต้องการทั้งสองอย่าง
Schemathesis และ Apidog: แต่ละตัวเหมาะกับอะไร
Apidog และ Schemathesis แก้ปัญหาที่แตกต่างกัน และทำงานได้ดีร่วมกัน Apidog เป็นแพลตฟอร์มแบบ all-in-one สำหรับการออกแบบ, การดีบัก, การทดสอบ, การจำลอง (mocking), และการจัดทำเอกสาร API Schemathesis เป็น fuzzer แบบ property-based ที่เน้นเฉพาะงาน การพูดตามตรงเกี่ยวกับขอบเขตมีความสำคัญที่นี่
Apidog ไม่ได้ทำการ property-based fuzzing คุณสมบัติที่ใกล้เคียงที่สุดคือ monkey testing ซึ่งส่งอินพุตแบบสุ่มเพื่อค้นหาข้อผิดพลาด นั่นมีประโยชน์ แต่ไม่เหมือนกับการทดสอบแบบ property-based ที่ขับเคลื่อนด้วย schema Schemathesis สร้างอินพุตจากข้อจำกัดในสเปกของคุณและตรวจสอบการตอบสนองเทียบกับ schema ดังนั้น หากคุณต้องการ property-based fuzzing ให้เลือกใช้ Schemathesis ไม่ใช่ Apidog
Apidog เหมาะกับส่วนที่เหลือของวงจรชีวิตรอบการ fuzzing นั้น
| ขั้นตอนของเวิร์กโฟลว์ | Schemathesis | Apidog |
|---|---|---|
| Property-based fuzzing จากสเปก | ใช่, คุณสมบัติหลัก | ไม่ |
| การออกแบบ API ด้วยภาพและการแก้ไขสเปก | ไม่ | ใช่ |
| การทดสอบเชิงฟังก์ชันแบบตัวอย่าง | จำกัด | ใช่, ตัวสร้างการทดสอบแบบภาพ |
| การทดสอบสัญญา (Contract testing) เทียบกับสเปก | บางส่วน, ผ่านการตรวจสอบ schema | ใช่, เวิร์กโฟลว์เฉพาะ |
| เซิร์ฟเวอร์จำลอง (Mock servers) จาก schema | ไม่ | ใช่, mock อัจฉริยะ |
| CI test runner | ใช่, st run |
ใช่, apidog run |
| เอกสารที่สร้างขึ้นโดยอัตโนมัติ | ไม่ | ใช่ |
การจับคู่ที่ใช้งานได้จริงมีลักษณะดังนี้ คุณออกแบบและดูแลรักษาสเปกใน Apidog, สร้างกรณีทดสอบเชิงฟังก์ชันและ mock server จากมัน, และรันสิ่งเหล่านั้นใน CI ด้วย apidog run จากนั้นคุณเพิ่ม Schemathesis เพื่อ fuzzing สเปกเดียวกันเพื่อค้นหาข้อผิดพลาดในกรณีขอบและการละเมิดสัญญา ทั้งสองเลเยอร์จะจับข้อบกพร่องที่แตกต่างกัน Apidog ยืนยันว่า API ทำสิ่งที่ถูกต้องสำหรับกรณีที่ทราบ; Schemathesis ค้นหากรณีที่ไม่รู้จักที่ทำให้มันล้มเหลว
หากเป้าหมายของคุณคือการเปลี่ยนสเปกให้เป็นชุดการทำงานที่รันได้ แทนที่จะเป็นการรันแบบ fuzzing, Apidog สามารถ สร้างชุดการทดสอบ API จาก OpenAPI specs ของคุณได้โดยตรง, และคุณสามารถ ดาวน์โหลด Apidog เพื่อลองเวิร์กโฟลว์นั้นได้
คำถามที่พบบ่อย
Schemathesis ฟรีหรือไม่?
ใช่ Schemathesis เป็นโอเพนซอร์สภายใต้ใบอนุญาต MIT และ CLI สามารถติดตั้งและรันได้ฟรีผ่าน pip install schemathesis นอกจากนี้ยังมีบริการเชิงพาณิชย์แบบโฮสต์สำหรับทีมที่ต้องการประสบการณ์แบบมีการจัดการ แต่เครื่องมือหลักที่คุณรันในเครื่องและใน CI นั้นไม่มีค่าใช้จ่าย
ความแตกต่างระหว่าง schemathesis run และ st run คืออะไร?
เป็นคำสั่งเดียวกัน st เป็นชื่อย่อของ schemathesis ดังนั้น st run และ schemathesis run จึงทำสิ่งเดียวกันทุกประการ ใช้แบบที่คุณชอบได้เลย ทั้งสองรับพาธหรือ URL ของ schema พร้อมตัวเลือกต่างๆ เช่น --url และ --header
Schemathesis สามารถแทนที่การทดสอบ API เชิงฟังก์ชันของฉันได้หรือไม่?
ไม่ และมันก็ไม่ได้ตั้งใจจะทำเช่นนั้น Schemathesis ตรวจสอบว่า API ของคุณไม่ล่มและการตอบสนองตรงกับ schema มันไม่ได้ตรวจสอบตรรกะทางธุรกิจ เช่น การคำนวณส่วนลดถูกต้องหรือไม่ คุณยังคงต้องการการทดสอบเชิงฟังก์ชันและ การทดสอบสัญญา (contract testing) แบบตัวอย่างสำหรับสิ่งนั้น ซึ่งคุณสามารถสร้างและรันได้ใน Apidog ถือว่า Schemathesis เป็นเลเยอร์ fuzzing เพิ่มเติม ไม่ใช่ตัวแทน
Schemathesis ใช้งานได้กับ GraphQL หรือไม่?
ใช่ Schemathesis รองรับทั้ง OpenAPI และ GraphQL schemas สำหรับ GraphQL มันจะสร้างคิวรีจากคำจำกัดความประเภทของ schema และตรวจสอบการตอบสนองในลักษณะเดียวกับที่ทำกับ REST APIs ที่กำหนดใน OpenAPI
บทสรุป
Schemathesis เป็นเครื่องมือที่เฉียบคมสำหรับงานเดียว: การนำ OpenAPI หรือ GraphQL spec ของคุณมาทดสอบความทนทานของ API ที่ทำงานอยู่ของคุณด้วยการสร้างแบบ property-based มันค้นหาข้อผิดพลาดและการละเมิดสัญญาที่การทดสอบแบบตัวอย่างพลาดไป และแทบไม่มีค่าใช้จ่ายใดๆ ในการเพิ่มเข้าสู่ CI สิ่งที่มันไม่ได้ทำคือการออกแบบ, การจำลอง (mock), การจัดทำเอกสาร, หรือการตรวจสอบตรรกะทางธุรกิจ
นั่นคือจุดที่ Apidog เข้ามาเติมเต็ม ออกแบบสเปก, สร้างการทดสอบเชิงฟังก์ชันและ mock, รันมันใน CI ด้วย apidog run, และจัดทำเอกสารผลลัพธ์ ทั้งหมดในที่เดียว จากนั้นจึงเพิ่ม Schemathesis เข้าไปสำหรับการ fuzzing ดาวน์โหลด Apidog เพื่อสร้างด้านการออกแบบและฟังก์ชันการทำงานของเวิร์กโฟลว์นั้น และให้ Schemathesis จัดการการค้นหากรณีขอบ