Prism End-to-End Contract Testing

ขอเล่า middleware ตัวนึงที่จะมาช่วยเรื่อง quality ให้ product เรารักษา quality ให้อยู่ได้อย่างสม่ำเสมอ ไม่พลาดขึ้น production ไปอย่างพลาดๆ

Prism คือ

https://meta.stoplight.io/docs/prism/README.md

Prism เป็นหนึ่งใน Product ของ Stoplight ที่พัฒนา collaborative platform นะครับ Product ของเค้าก็มีหลายตัว ลองเข้าไปดูรายละเอียดของได้ทางเว็บหลักเค้าได้เลย https://meta.stoplight.io/

ถ้าได้ค่าโฆษณาด้วยจะช่วยขายของมากกว่านี้ 🤑

ตามที่เค้าโฆษณาครับ Prism สามารถทำ API Mock Server และ Contract Testing ได้ แต่ในบทความนี้จะเล่าถึงแค่ Contract Test นะครับ ไวมีโอกาสจะมาเล่าการทำ API Mock ให้อ่านกันครับ

Contract Testing คืออะไร

สิ่งที่ต้องมี

ถ้าได้อ่าน "Contract Testing คืออะไรแล้ว" จะเห็นว่ามันใช้งานคู่กับ API Spec เพื่อเอาไวตรวจสอบ Response ของ API นะครับ

ดังนั้นเจ้า Prism เนี่ยก็ต้องการเช่นกัน โดยที่เจ้า Prism ก็ support API Spec ของ OpenAPI ที่เป็น Standard ที่ใครๆ ก็ใช้กัน ดังนั้นสิ่งที่ขาดไม่ได้คือต้องมี file .yaml หรือ .json ที่เป็น OpenAPI ก่อนนะครับ

• OpenAPI ชื่อเดิมคือ Swagger Specification นะครับ น่าจะคุ้นกันมากขึ้น

• Prism support OpenAPI v2 กับ v3 นะครับ

1. File *.yaml หรือ *.json ที่เป็น OpenAPI

2. node.js และ npm

3. Web API ที่ Response ได้ตาม spec ข้อ 1

4. หลังจากติดตั้งข้อ 2 แล้วติดตั้ง prism-cli

ข้อ 1

ทำ spec ง่ายๆ ไว test สักตัวเดียวพอ

save file ชื่อ account.yaml

---
openapi: 3.0.0
info:
  title: Test Prism
  version: v1

paths:
  '/api/accounts/profile':
    get:      
      description: 'Example get accounts'
      tags:
        - Accounts
      parameters:
        - in: query
          name: type
          schema:
            type: string
            enum:
              - active
              - inactive
      responses:
        "200":
          description: A user object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accounts'   # Reference to an object
              examples:
                success:
                  value:
                    items:
                    - id: "1"
                      name: "Jessica Smith"
                      account_type: "active"
                    - id: "2"
                      name: "Tony Smith"
                      account_type: "inactive"
components:
  schemas:
    accounts:  # Schema name
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: 1
              name:
                type: string
                example: my name
              account_type:
                type: string
                example: active
                enum: [active,inactive]

ข้อ 2

👉 https://nodejs.org/en/download/

ข้อ 3

ไหนๆ ลง node แล้วก็ใช้ node.js + express เลยแล้วกัน

npm install express

ตามด้วย code ทำ Web API สั้นๆ สัก 1 API แต่ต้องให้มันเหมือน spec ที่ทำที่ข้อ 1 ด้วยนะ

save file ชื่อ prism-test.js

var express = require('express');
var app = express();

app.get('/api/accounts/profile', (req, res) => {
    res.json({
        items: [
            {
                "id": "1",
                "name": "testname",
                "account_type": "active"
            },
            {
                "id": "2",
                "name": "testname",
                "account_type": "deleted"
            }
        ]
    });
});

app.listen(4000, () => {
    console.log('Start server at port 4000.')
});

จาก code นี้ผมตั้งใจให้มัน response ผิดนะครับ จะได้เห็นภาพตอน test กันเนอะ

ข้อ 4

npm install -g @stoplight/prism-cli

หลังจากติดตั้งเสร็จหมดแล้วเปิด terminal แล้วลองพิมพ์ prism --version ดูต้องแสดง version ออกมาครับ

เริ่มกันเลยดีกว่า

เปิด Terminal ขึ้นมาครับแล้ว start Web API ที่เราทำไวก่อนเลย

node prism-test.js

ตามด้วย start เจ้า prism ให้มาทำงานเป็น proxy ให้เรา format ของ prism cil เป็นแบบนี้ครับ

prism proxy <file OpenAPI (*.yaml , *.json)> <web api server> --errors

ตรง --errors นี้สำคัญนะครับ

เราก็แทนที่ด้วย file ของเรา กับ Web API ของเราที่ทำไว้

prism proxy account.yaml http://127.0.01:4000 --errors

หลังจากกด enter แล้วเจ้า prism จะจำลองตัวเองเป็น proxy server ขึ้นมาให้ครับ defalt คือ 127.0.0.1:4010 เพื่อให้เราเรียกใช้งาน

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

เวลาเรียกที่ Postman ปกติเราจะเรียกไปที่ Web API Server ของเราจริงๆ อันนี้ก็ให้เปลี่ยนเป็นเรียกผ่าน prism proxy แทนครับ หากเรียกแล้วทุกอย่าง Respones ตาม Spec หมดเราจะได้ Response ที่ถูกต้องมาตามจริงมาเลยครับ แต่ใน case ที่ไม่ตรงตาม Spec ก็จะได้ Error มาโดย Error ที่ได้มาเนี่ย มันจะบอกด้วยนะว่าเทียบกับ Spec แล้วผิดตรงไหน เจ้า prism เนี่ยมันจะ validate ให้ทั้งตอน request และ response เลย

กรณี request ไปแบบผิดๆ

ส่ง query string type=deleted ซึ่ง spec บอกไวว่าจะมีแค่ active และ inactive

กรณี request ถูกต้องหมดแต่ response ที่ได้กลับมาไม่ตรงตาม spec

• ถ้าดูใน cod ผมตั้งใจให้ response item ที่ 2 มี account_type=deleted

• spec บอก account_type จะมีแค่ active และ inactive

หลังจาก Request ผ่าน Postman ไปแล้วจะเห็น Result ผ่าน Terminal ด้วยเช่นกันครับ

จะเห็นว่าถ้าเป็นแบบนี้อาจจะเกิด blocker ได้เนื่องจากพอเจอว่า API ทำงานไม่ตรงตาม spec มันก็จะไม่ response ไปตามที่ API ส่งมาจริงๆ ทำให้เราอาจจะไม่เห็นผลกระทบจริงๆ ของ consumer ที่ request มา ดังนั้นเราอาจจะต้องการให้ response กลับไปหา consumer เลยจริงๆ เพื่อให้รู้ผลกระทบที่เกิดขึ้นหรือถ้า consumer มีทำ unit test ไวอยู่แล้วเราก็จะได้เห็นด้วยว่าเกิดอะไรขึ้นกับ consumer บางใน case ที่ผิดพลาด

เราสามารถทำได้ง่ายๆ เลยตอน run prism proxy เราแค่ไม่ต้องส่ง --errors ไปแค่นั้นครับ ลองกันเลย

prism proxy account.yaml http://127.0.01:4000

จากนั้นเราลองเอา Postman เรียกดูอีกทีครับ

จะเห็นว่าเราได้ response มาจาก API ตามจริงกลับมาเลยคือที่มี account_type=deleted ที่ไม่ตรงตาม spec แล้วเราลองไปดูที่ terminal ครับ

จะเห็นว่าเราจะเห็น error description แสดงบน terminal แทนครับ

อันนี้เป็นตัวอย่างที่ทำไวแค่ 1 API ครับ ตามความเป็นจริงเราก็สามารถใช้วิธีการเดียวกันได้กับทุก API ที่เรามี ทุกครั้งที่มีการเปลี่ยนแปลงหาก Frontend ไม่ได้ทำอะไรแต่ Backend มีการเพิ่ม Featrue เราก็สามารถ run contract test เพื่อดูก่อนว่ายังตรงตาม Spec ที่คุยกันไวอยู่หรือไม ทำให้บางครั้งอาจจะไม่จำเป็นต้อง E2E test เลยก็ได้

จบแล้วรายละเอียดของเจ้า Prism ขอบคุณครับ

อันนี้ Prism Tower จาก Red Alert ไม่เกี่ยวกับเนื้อหาแต่อยากลง

Reference

• Feature เต็มๆ ของเจ้า "Prism" นะครับ https://meta.stoplight.io/docs/prism/README.md

• Featrue อื่นๆ ของ Prism ในการทำ Contract Test https://meta.stoplight.io/docs/prism/docs/guides/03-validation-proxy.md