วิธีทำ API Contract Testing: แนวทางปฏิบัติที่ดีที่สุดสำหรับ API ที่เชื่อถือได้

คุณเคยประสบสถานการณ์ที่แอปพลิเคชันส่วนหน้า (frontend) ของคุณพังลงกะทันหันเพราะ API ส่วนหลัง (backend) มีการเปลี่ยนแปลงโดยไม่คาดคิดหรือไม่? การหยุดชะงักดังกล่าวสามารถส่งผลกระทบต่อเนื่องไปทั่วทั้งระบบของคุณ ทำให้ผู้ใช้หงุดหงิด และต้องใช้เวลาในการแก้ไขข้อผิดพลาดอย่างเร่งรีบ นี่คือจุดที่การทดสอบสัญญา API (API Contract Testing) เข้ามามีบทบาท ซึ่งเป็นแนวทางที่เป็นระบบที่ช่วยให้มั่นใจได้ถึงความสอดคล้องกันระหว่างผู้ผลิตและผู้บริโภค API ในคู่มือนี้ เราจะเจาะลึกความแตกต่างของการทดสอบสัญญา API สำรวจพื้นฐาน ความท้าทาย และกลยุทธ์การทำงานอัตโนมัติ เมื่ออ่านจบ คุณจะเข้าใจว่าทำไมการทดสอบสัญญา API ไม่ใช่แค่สิ่งที่ "มีไว้ก็ดี" แต่เป็นรากฐานสำคัญของการพัฒนาซอฟต์แวร์ที่แข็งแกร่ง ให้เราเริ่มต้นการเดินทางนี้ไปด้วยกัน ค้นพบวิธีผสานรวมการทดสอบสัญญา API เข้ากับขั้นตอนการทำงานของคุณได้อย่างราบรื่น

💡

ต้องการเครื่องมือทดสอบ API ที่ยอดเยี่ยมที่สร้างเอกสารประกอบ API ที่สวยงามหรือไม่?

ต้องการแพลตฟอร์มแบบครบวงจรที่ทีมพัฒนาของคุณสามารถทำงานร่วมกันได้อย่างมีประสิทธิภาพสูงสุดหรือไม่?

Apidog ตอบสนองทุกความต้องการของคุณ และเข้ามาแทนที่ Postman ในราคาที่ย่อมเยากว่ามาก!

ปุ่ม

การทดสอบสัญญา API (API Contract Testing) คืออะไร?

การทดสอบสัญญา API (API Contract Testing) ช่วยให้มั่นใจว่าอินเทอร์เฟซที่ตกลงกันไว้ระหว่างผู้ให้บริการ API และผู้ใช้จะคงความสอดคล้องกันเมื่อระบบมีการพัฒนา สัญญาดังกล่าวถูกกำหนดผ่านสเปกของ OpenAPI หรือ Swagger ซึ่งจะอธิบายโครงสร้างการร้องขอและการตอบกลับที่คาดหวัง—เช่น จุดเชื่อมต่อ (endpoints), วิธีการ (methods), สกีมา (schemas), ส่วนหัว (headers) และรหัสสถานะ (status codes)—ซึ่งคล้ายกับข้อตกลงอย่างเป็นทางการที่ทั้งสองฝ่ายใช้เป็นเกณฑ์

การทดสอบสัญญา API โดยทั่วไปมีสองรูปแบบ สัญญาที่ขับเคลื่อนโดยผู้ใช้ (Consumer-Driven Contracts - CDCs) กำหนดความคาดหวังจากมุมมองของผู้ใช้เพื่อป้องกันความล้มเหลวในการรวมระบบในไมโครเซอร์วิส ส่วนสัญญาที่กำหนดโดยผู้ให้บริการ ซึ่งสร้างโดยทีม API จะครอบคลุมการโต้ตอบที่รองรับทั้งหมดเพื่อการตรวจสอบที่ครอบคลุมมากขึ้น ไม่เหมือนกับการทดสอบฟังก์ชันการทำงานหรือยูนิต การทดสอบเหล่านี้มุ่งเน้นไปที่อินเทอร์เฟซของ API อย่างเคร่งครัด ไม่ใช่ตรรกะเบื้องหลัง

ความสำคัญของการทดสอบสัญญา API

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

ประโยชน์สำคัญของการทดสอบสัญญา API ได้แก่:

ตรวจจับการเปลี่ยนแปลงที่ส่งผลกระทบในวงกว้างได้ตั้งแต่เนิ่นๆ
ความน่าเชื่อถือในระบบแบบกระจาย (distributed systems)
การปรับใช้ (deployment) ที่ปลอดภัยและมั่นใจได้
การพัฒนาแบบขนาน
เวิร์กโฟลว์ CI/CD ที่แข็งแกร่งขึ้น
การบำรุงรักษาในระยะยาว

ในสภาพแวดล้อมที่รวดเร็วและวนซ้ำ เช่น อีคอมเมิร์ซหรือ SaaS การทดสอบสัญญา API ถือเป็นสิ่งสำคัญในการส่งมอบแอปพลิเคชันที่เสถียร คาดเดาได้ และใช้งานง่าย

ความท้าทายของการทดสอบสัญญา API ด้วยตนเอง

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

ความท้าทายสำคัญของการทดสอบสัญญา API ด้วยตนเอง ได้แก่:

ใช้ความพยายามและต้นทุนเวลาสูง
ข้อผิดพลาดจากมนุษย์
ปรับขนาดได้ไม่ดี
ภาระการประสานงานในทีมแบบกระจาย
ความเชื่อมั่นที่ลดลง

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

เริ่มต้นใช้งาน API Contract Testing ใน Apidog

พร้อมที่จะนำ การทดสอบสัญญา API ไปใช้ในโปรเจกต์ของคุณแล้วหรือยัง? Apidog แพลตฟอร์มการพัฒนา API ที่ครอบคลุม ช่วยให้เรื่องนี้ง่ายขึ้นด้วยการตรวจสอบสกีมาในตัวและความสามารถในการเขียนสคริปต์ ทำให้เป็นจุดเริ่มต้นที่เหมาะอย่างยิ่ง

หากต้องการเปิดใช้งานการทดสอบสัญญา API ใน Apidog ให้เริ่มต้นด้วยการนำเข้าสเปก OpenAPI ของคุณ หรือสร้างโปรเจกต์ใหม่—Apidog จะสร้างการทดสอบจากสกีมาโดยอัตโนมัติ ทำให้การตั้งค่าเป็นไปอย่างราบรื่น

สำหรับตัวอย่างภาคปฏิบัติ มาใช้โปรเจกต์ Pet Store สาธิตของ Apidog ซึ่งเป็นโปรเจกต์คลาสสิกสำหรับการสำรวจ API เปิด Apidog เลือกโปรเจกต์ "Demo Pet" และไปยัง GET endpoint "/pet/{petId}" (หมายเหตุ: การสืบค้นใช้ "/get/pets/{id}" แต่เพื่อให้สอดคล้องกับ Petstore มาตรฐาน จะเป็น "/pet/{petId}") ตั้งค่าสภาพแวดล้อมเป็น "petstore env" หรือ "localmock" ผ่านเมนูดรอปดาวน์ด้านซ้ายบน

จากนั้นดำเนินการร้องขอ คุณจะได้รับการตอบกลับดังนี้:

{
  "id": 1,
  "category": {
    "id": 1,
    "name": "dogs"
  },
  "name": "doggie",
  "photoUrls": [],
  "tags": [],
  "status": "available"
}

นี่เป็นการเตรียมความพร้อมสำหรับการตรวจสอบสัญญา

ไปที่แท็บ "Test Cases" และสร้างชุดการทดสอบใหม่โดยคลิก "Add Case"

ในส่วน pre-processors ให้เพิ่มสคริปต์ที่กำหนดเองเพื่อกำหนด JSON schema และตัวแปรของคุณ:

ขั้นตอนที่ 1: ไปที่ Pre-Processors

การสร้างสคริปต์ทดสอบที่กำหนดเองใน Apidog

ขั้นตอนที่ 2: เพิ่มโค้ด JS ที่กำหนดเอง

การเพิ่มโค้ดสคริปต์ทดสอบ JS ที่กำหนดเองใน Apidog

// Set petId if not set (as string)
if (!pm.environment.get("petId")) {
  pm.environment.set("petId", "1");
}

// Define JSON schema for the pet response
const petSchema = {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "category": {
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "name": { "type": "string" }
      },
      "required": ["id", "name"],
      "additionalProperties": true
    },
    "name": { "type": "string" },
    "photoUrls": {
      "type": "array",
      "items": { "type": "string", "format": "uri" },
      "minItems": 0
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" }
        },
        "required": ["id", "name"],
        "additionalProperties": true
      },
      "minItems": 0
    },
    "status": {
      "type": "string",
      "enum": ["available", "pending", "sold"]
    }
  },
  "required": ["id", "name", "photoUrls", "status"],
  "additionalProperties": true
};

// Store the schema in an environment variable (stringify it)
pm.environment.set("pet_schema", JSON.stringify(petSchema));

// (Optional) log to console for debugging
console.log("Pre-processor: petId =", pm.environment.get("petId"));

ถัดไป ใน post-processors ให้วางสคริปต์การตรวจสอบ:

เพิ่มสคริปต์ post-processors ที่กำหนดเอง

// Use AJV for schema validation
var Ajv = require('ajv');
var ajv = new Ajv({ allErrors: true, logger: console });

// Retrieve schema from environment
var raw = pm.environment.get("pet_schema");
var schema;
try {
  schema = (typeof raw === 'string') ? JSON.parse(raw) : raw;
} catch (err) {
  pm.test('Schema is valid JSON', function() {
    pm.expect(false, 'pet_schema is not valid JSON: ' + err.message).to.be.true;
  });
  // Stop further tests
  return;
}

// Parse the response body as JSON
var responseData;
try {
  responseData = pm.response.json();
} catch (err) {
  pm.test('Response is valid JSON', function() {
    pm.expect(false, 'Response body is not JSON: ' + err.message).to.be.true;
  });
  return;
}

// Test status code
pm.test('Status code is 200', function() {
  pm.expect(pm.response.status).to.eql("OK");
});

// Validate schema
pm.test('Response matches pet schema', function() {
  var valid = ajv.validate(schema, responseData);
  if (!valid) {
    console.log('AJV Errors:', ajv.errors);
  }
  pm.expect(valid, 'Response does not match schema, see console for errors').to.be.true;
});

// Additional assertions
pm.test('Returned id matches requested petId', function() {
  var requested = pm.environment.get("petId");
  // petId is stored as string, but id in response is integer
  var requestedNum = Number(requested);
  if (!isNaN(requestedNum)) {
    pm.expect(responseData.id).to.eql(requestedNum);
  } else {
    pm.expect(String(responseData.id)).to.eql(String(requested));
  }
});

pm.test('Name is a string', function() {
  pm.expect(responseData.name).to.be.a('string');
});

pm.test('Status is one of expected values', function() {
  pm.expect(responseData.status).to.be.oneOf(['available', 'pending', 'sold']);
});

// Optional: more detailed checks (category, photoUrls, tags)
pm.test('Category has id and name', function() {
  pm.expect(responseData.category).to.have.property('id');
  pm.expect(responseData.category).to.have.property('name');
});

pm.test('At least one photo URL', function() {
  pm.expect(responseData.photoUrls).to.be.an('array').that.is.not.empty;
});

pm.test('Tags are valid objects', function() {
  pm.expect(responseData.tags).to.be.an('array');
  if (responseData.tags.length > 0) {
    responseData.tags.forEach(function(tag) {
      pm.expect(tag).to.have.property('id');
      pm.expect(tag).to.have.property('name');
    });
  }
});

กด "Run" เพื่อดำเนินการ Apidog จะแสดงผลลัพธ์ทางด้านขวา: "Passed" (ผ่าน) หรือ "Failed" (ไม่ผ่าน) พร้อมรายละเอียดที่ขยายได้ การรันที่สำเร็จอาจแสดง:

การตอบกลับของ API:

{
  "id": 1,
  "category": {
    "id": 1,
    "name": "dog"
  },
  "name": "Jasper",
  "photoUrls": [
    "https://loremflickr.com/400/400?lock=7187959506185006"
  ],
  "tags": [
    {
      "id": 3,
      "name": "Yellow"
    }
  ],
  "status": "available"
}

การทดสอบที่ผ่าน:

รหัสสถานะคือ 200
การตอบกลับตรงกับ pet schema
id ที่ส่งกลับมาตรงกับ petId ที่ร้องขอ
Name เป็นสตริง
Status เป็นหนึ่งในค่าที่คาดหวัง
Category มี id และ name
มี URL รูปภาพอย่างน้อยหนึ่งรายการ
Tags เป็นออบเจกต์ที่ถูกต้อง

หากต้องการจำลองความล้มเหลว ให้แก้ไขการทดสอบรหัสสถานะให้คาดหวังเป็นตัวเลข (200) แทน "OK,"

จากนั้นรันซ้ำและสังเกตข้อผิดพลาดในการยืนยัน

บันทึกชุดการทดสอบสำหรับการรันแบบ regression อินเทอร์เฟซที่ใช้งานง่ายของ Apidog พร้อมการผสานรวม AJV สำหรับการตรวจสอบสกีมา ทำให้การทดสอบสัญญา API เป็นเรื่องง่ายขึ้น เปลี่ยนการตรวจสอบที่ซับซ้อนให้เป็นงานประจำวัน

คำถามที่พบบ่อย

คำถามที่ 1. อะไรคือความแตกต่างระหว่างการทดสอบสัญญา API (API Contract Testing) กับการทดสอบการรวมระบบ (integration testing)?

คำตอบ: การทดสอบสัญญา API จะตรวจสอบสัญญาอินเทอร์เฟซโดยไม่รันตรรกะทางธุรกิจ ในขณะที่การทดสอบการรวมระบบจะตรวจสอบว่าบริการต่างๆ โต้ตอบกันอย่างไร รวมถึงการไหลของข้อมูลและ dependency ต่างๆ

คำถามที่ 2. สามารถใช้ API Contract Testing กับ GraphQL API ได้หรือไม่?

คำตอบ: ได้ แม้ว่าโดยหลักแล้วจะออกแบบมาสำหรับ REST แต่เครื่องมืออย่าง Pact ก็รองรับ GraphQL schemas โดยเน้นที่โครงสร้างการสืบค้น/การตอบกลับและการเปลี่ยนแปลงข้อมูล (mutations)

คำถามที่ 3. ควรมีการรัน API Contract Testing บ่อยแค่ไหนใน CI/CD pipeline?

คำตอบ: ตามหลักการแล้ว ควรรันทุกครั้งที่มีการคอมมิต (commit) หรือพูลรีเควสต์ (pull request) เพื่อตรวจจับปัญหาตั้งแต่เนิ่นๆ และรันตอนกลางคืนเพื่อครอบคลุมการทดสอบอย่างสมบูรณ์

คำถามที่ 4. จะทำอย่างไรหากทีมของฉันไม่มี OpenAPI spec สำหรับการทดสอบสัญญา?

คำตอบ: เริ่มต้นด้วยการสร้าง spec จากโค้ดที่มีอยู่โดยใช้เครื่องมืออย่าง Swagger Codegen จากนั้นปรับปรุงร่วมกันเพื่อสร้างพื้นฐาน

คำถามที่ 5. API Contract Testing เหมาะสำหรับ Legacy API หรือไม่?

คำตอบ: เหมาะสมอย่างยิ่ง—ปรับปรุง spec เพื่อจัดทำเอกสารพฤติกรรมปัจจุบัน จากนั้นทำการทดสอบอัตโนมัติเพื่อป้องกันการถดถอยระหว่างการปรับปรุงให้ทันสมัย

สรุป

เมื่อเราได้สำรวจเรื่องนี้มาถึงบทสรุป ก็เป็นที่ชัดเจนว่าการทดสอบสัญญา API (API Contract Testing) เป็นหัวใจสำคัญสำหรับ API ที่เชื่อถือได้และปรับขนาดได้ในโลกที่เชื่อมโยงถึงกัน ตั้งแต่การลดความซ้ำซ้อนด้วยตนเอง ไปจนถึงการเสริมสร้างมาตรการป้องกันอัตโนมัติ ช่วยให้ทีมงานสามารถสร้างสรรค์สิ่งใหม่ๆ ได้โดยไม่ต้องกังวล ใช้เครื่องมืออย่าง Apidog เพื่อยกระดับการทำงานของคุณ และเฝ้าดูแอปพลิเคชันของคุณได้รับความยืดหยุ่นและประสิทธิภาพ ไม่ว่าจะเป็นการปรับปรุงสัญญาที่มีอยู่หรือการสร้างสัญญาใหม่ เส้นทางสู่การกำกับดูแล API ที่เหนือกว่าเริ่มต้นด้วยการทดสอบเพียงครั้งเดียวที่กำหนดไว้อย่างดี

💡

ปุ่ม