วิธีรันการทดสอบ API ด้วย Apidog CLI บน CircleCI

ในการรัน Apidog CLI API tests ใน CircleCI ให้เพิ่มไฟล์ .circleci/config.yml ที่ใช้ Docker executor cimg/node ติดตั้ง apidog-cli ด้วย npm และรัน apidog run ด้วย access token, test scenario ID และ environment ID ของคุณ จัดเก็บ token และ ID เหล่านี้เป็นตัวแปรสภาพแวดล้อม (environment variables) ของ CircleCI จากนั้นเผยแพร่รายงาน JUnit และ HTML ด้วย store_test_results และ store_artifacts คู่มือนี้จะแนะนำแต่ละส่วนเพื่อให้คุณสามารถคัดลอก วาง และนำไปใช้งานได้

บทความนี้เกี่ยวกับการรันการทดสอบ ไม่ใช่การเลือกแพลตฟอร์ม CI หากคุณยังคงตัดสินใจเลือกระหว่างเครื่องมือต่างๆ การเปรียบเทียบ CircleCI กับ Jenkins ครอบคลุมเรื่องนั้นไว้แล้ว ในที่นี้ เราสมมติว่าคุณได้เลือก CircleCI แล้วและต้องการให้ชุด API ของคุณทำงานทุกครั้งที่มีการพุชโค้ด

CircleCI คืออะไรและทำงานอย่างไร

CircleCI คือบริการ Continuous Integration และ Delivery แบบคลาวด์ มันจะคอยตรวจสอบ Git repository ของคุณ และเมื่อคุณพุชคอมมิต มันจะรันขั้นตอนการสร้าง (build), การทดสอบ (test) และการปรับใช้ (deploy) ที่คุณกำหนดไว้ คุณอธิบายขั้นตอนเหล่านั้นในไฟล์ YAML ไฟล์เดียว ดังนั้นไพพ์ไลน์ของคุณจึงอยู่ในระบบควบคุมเวอร์ชันพร้อมกับโค้ดของคุณ

ทุกอย่างเริ่มต้นด้วยไฟล์ .circleci/config.yml ที่รูทของ repo ของคุณ CircleCI จะอ่านไฟล์นี้ทุกครั้งที่มีการพุชและแปลงให้เป็นไพพ์ไลน์ รูปแบบการกำหนดค่าปัจจุบันคือเวอร์ชัน 2.1 ซึ่งเพิ่มส่วนประกอบที่นำกลับมาใช้ใหม่ได้ เช่น orbs, commands และ parameters นอกเหนือจากเอนจินพื้นฐาน 2.0

การกำหนดค่า CircleCI มีแนวคิดหลักสามประการ:

• งาน (Jobs) คือหน่วยของการทำงาน แต่งานแต่ละงานจะรันชุดของ ขั้นตอน (steps) เช่น การเช็คเอาต์โค้ด การติดตั้งdependencies หรือการรันคำสั่งทดสอบ
• ตัวดำเนินการ (Executors) กำหนดว่างานจะทำงานที่ใด Docker executor จะรันขั้นตอนของคุณภายในอิมเมจคอนเทนเนอร์ที่คุณเลือก เช่น cimg/node สำหรับโปรเจกต์ Node.js
• เวิร์กโฟลว์ (Workflows) จัดการงาน เวิร์กโฟลว์จะตัดสินใจว่างานใดจะทำงาน ในลำดับใด และจะทำงานแบบขนานหรือตามลำดับ

การแยกส่วนนี้มีความสำคัญสำหรับการทดสอบ API คุณกำหนดงานหนึ่งงานที่ติดตั้ง Apidog CLI และรันสถานการณ์จำลองของคุณ จากนั้นเวิร์กโฟลว์จะทริกเกอร์งานนั้นบนสาขา (branches) ที่คุณสนใจ

ทำไมต้องรัน API tests ใน CircleCI

การรันชุด API ของคุณใน CI จะช่วยตรวจจับการละเมิดสัญญา (contract breaks) ก่อนที่จะถึงขั้นตอนการผลิต การเปลี่ยนแปลงโครงสร้าง (schema change), การเปลี่ยนชื่อฟิลด์ หรือโฟลว์การยืนยันตัวตนที่เสีย จะแสดงเป็นบิลด์สีแดงแทนที่จะเป็นตั๋วสนับสนุน

Apidog CLI สร้างมาเพื่อสิ่งนี้โดยเฉพาะ คุณออกแบบและดีบักสถานการณ์จำลองการทดสอบในแอป Apidog จากนั้นรันสถานการณ์จำลองเดียวกันนั้นแบบ headless ใน CI ด้วยคำสั่งเดียว ไม่ต้องเขียน assertions ใหม่ในโค้ด และไม่ต้องดูแลรักษาชุดทดสอบแยกต่างหาก

หากคุณต้องการเห็นภาพรวมที่กว้างขึ้นว่าการตรวจสอบอัตโนมัติเข้ากับไพพ์ไลน์ได้อย่างไร คู่มือ 12 แนวปฏิบัติที่ดีที่สุดของ CI/CD สำหรับการทดสอบ API เป็นแหล่งข้อมูลที่อ่านควบคู่กันได้ดี

สิ่งที่ต้องเตรียม

ก่อนที่คุณจะเขียนการกำหนดค่า ให้เตรียมสิ่งเหล่านี้ให้พร้อมในแอป Apidog:

• access token สร้างได้ภายใต้การตั้งค่าบัญชี Apidog ของคุณ สิ่งนี้ใช้สำหรับการยืนยันตัวตนของ CLI ในสภาพแวดล้อมแบบ headless คู่มือการยืนยันตัวตน Apidog CLI ครอบคลุมการสร้างโทเค็นและการจัดการความลับของ CI โดยละเอียด
• ID สถานการณ์จำลองการทดสอบ (test scenario ID) เปิดสถานการณ์จำลองการทดสอบที่คุณต้องการรันและคัดลอก ID จาก URL หรือการตั้งค่าสถานการณ์จำลอง
• ID สภาพแวดล้อม (environment ID) สิ่งนี้จะบอก CLI ว่าควรใช้ URL พื้นฐานและตัวแปรใด เช่น staging หรือ production

คุณจะต้องมีบัญชี CircleCI ที่เชื่อมต่อกับ Git provider ของคุณด้วย โดยเปิดใช้งานโปรเจกต์ในแดชบอร์ด CircleCI แล้ว

จัดเก็บความลับเป็นตัวแปรสภาพแวดล้อม

อย่าฮาร์ดโค้ด access token ของคุณใน config.yml เด็ดขาด ไฟล์นี้ถูกคอมมิตไปยัง Git ดังนั้นโทเค็นที่อยู่ในนั้นจึงเป็นโทเค็นที่รั่วไหลได้

CircleCI มีสองตัวเลือกที่ปลอดภัยให้คุณ:

• ตัวแปรสภาพแวดล้อมของโปรเจกต์ (Project environment variables) ใน UI ของ CircleCI ให้เปิด Project Settings จากนั้น Environment Variables และเพิ่มค่าแต่ละค่าลงไป ตัวแปรเหล่านี้จะถูกเข้ารหัสและเปิดเผยต่องานในรูปของ $VARS
• บริบท (Contexts) บริบทคือกลุ่มของตัวแปรสภาพแวดล้อมที่มีชื่อซึ่งใช้ร่วมกันได้ในหลายโปรเจกต์ คุณสร้างได้ภายใต้ Organization Settings จากนั้น Contexts และอ้างอิงจากเวิร์กโฟลว์ บริบทมีประโยชน์เมื่อหลาย repo ใช้ Apidog token เดียวกัน

สำหรับคู่มือนี้ ให้เพิ่มตัวแปรสามตัว: APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID และ APIDOG_ENVIRONMENT_ID CLI จะอ่านค่าเหล่านี้ในขณะรันไทม์ และไม่มีข้อมูลที่ละเอียดอ่อนใดๆ อยู่ใน repo ของคุณ

ไฟล์ config.yml ฉบับเต็ม

นี่คือการกำหนดค่าที่สมบูรณ์แบบที่สามารถคัดลอกและวางได้ วางไฟล์นี้ที่ .circleci/config.yml ตั้งค่าตัวแปรสภาพแวดล้อมทั้งสามของคุณ แล้วพุชได้เลย

version: 2.1

jobs:
  api-tests:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run:
          name: Install Apidog CLI
          command: npm install -g apidog-cli
      - run:
          name: Run Apidog API tests
          command: |
            apidog run \
              --access-token $APIDOG_ACCESS_TOKEN \
              -t $APIDOG_TEST_SCENARIO_ID \
              -e $APIDOG_ENVIRONMENT_ID \
              -r cli,junit,html \
              --out-dir ./reports
      - store_test_results:
          path: ./reports
      - store_artifacts:
          path: ./reports

workflows:
  test-api:
    jobs:
      - api-tests

ผมจะอธิบายว่าแต่ละส่วนทำอะไรบ้าง

ตัวดำเนินการ (executor)

docker:
  - image: cimg/node:20.11

cimg/node เป็นอิมเมจที่ CircleCI จัดเตรียมไว้สำหรับ Node.js ซึ่งมาพร้อมกับ Node, npm และเครื่องมือสร้างทั่วไปที่ติดตั้งไว้ล่วงหน้า ทำให้ npm install -g apidog-cli ทำงานได้โดยไม่ต้องตั้งค่าเพิ่มเติม แท็ก :20.11 กำหนดเวอร์ชันของ Node; ให้กำหนดเวอร์ชันที่ทีมของคุณใช้เป็นมาตรฐาน

ขั้นตอน (steps)

checkout จะดึง repository ของคุณมาไว้ในไดเรกทอรีการทำงานของ job ขั้นตอน run แรกจะติดตั้ง CLI แบบ global ขั้นตอน run ที่สองจะรันการทดสอบของคุณ

ดูคำสั่งทดสอบอย่างละเอียด:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports

แต่ละแฟล็ก (flag) มีหน้าที่เดียว:

• --access-token ใช้สำหรับการยืนยันตัวตนของการรัน ไม่มีรูปแบบย่อ
• -t เลือกสถานการณ์จำลองการทดสอบด้วย ID
• -e เลือกสภาพแวดล้อม แฟล็กนี้จำเป็น; CLI ต้องทราบว่าจะใช้ URL พื้นฐานและตัวแปรใด
• -r ตั้งค่า reporters ในที่นี้คุณร้องขอสามอย่าง: cli พิมพ์ผลลัพธ์แบบเรียลไทม์ไปยังบันทึกการสร้าง, junit เขียน XML ที่เครื่องอ่านได้ และ html เขียนรายงานที่สามารถเรียกดูได้
• --out-dir บอก CLI ว่าจะเขียนไฟล์รายงานไปที่ใด

การเผยแพร่รายงาน

- store_test_results:
    path: ./reports
- store_artifacts:
    path: ./reports

store_test_results จะชี้ CircleCI ไปยัง JUnit XML ใน ./reports CircleCI จะแยกวิเคราะห์และแสดงแท็บ Tests บนบิลด์ ดังนั้นข้อผิดพลาดจะแสดงเป็นรายการตามชื่อพร้อมข้อมูลเวลา นี่คือสิ่งที่เปลี่ยนข้อความบันทึกจำนวนมากให้เป็นมุมมองการผ่าน/ไม่ผ่านที่มีโครงสร้าง

store_artifacts จะอัปโหลดไดเรกทอรีเดียวกันเป็นไฟล์ที่ดาวน์โหลดได้ ซึ่งรวมถึงรายงาน HTML หลังจากบิลด์เสร็จสิ้น คุณสามารถเปิดแท็บ Artifacts และดูรายงานที่แสดงผลในเบราว์เซอร์ของคุณได้ คู่มือรายงานการทดสอบ Apidog CLI อธิบายรูปแบบ CLI, HTML และ JSON โดยละเอียดมากขึ้น

เวิร์กโฟลว์ (workflow)

workflows:
  test-api:
    jobs:
      - api-tests

เวิร์กโฟลว์นี้จะรัน job api-tests ทุกครั้งที่มีการพุช คุณสามารถเพิ่มตัวกรองเพื่อจำกัดให้ทำงานเฉพาะบนบางสาขา (branches) หรือเพิ่ม job อื่นๆ ที่รันก่อนหรือหลังได้ สำหรับ job การทดสอบเดียว บล็อกขั้นต่ำนี้ก็เพียงพอแล้ว

รันการทดสอบเฉพาะบนสาขา main

คุณอาจไม่ต้องการรัน API เต็มรูปแบบบนทุก feature branch ให้เพิ่มตัวกรองสาขา (branch filter) ไปยังเวิร์กโฟลว์:

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop

ตอนนี้ job จะรันเฉพาะการพุชไปยัง main และ develop เท่านั้น สาขาอื่นๆ จะถูกข้ามไป ซึ่งจะช่วยให้เวลาการบิลด์ของคุณเน้นไปที่สาขาที่จะส่งมอบ

ใช้ Context แทนตัวแปรโปรเจกต์

หาก repository หลายแห่งใช้ Apidog token เดียวกัน Context จะช่วยเก็บไว้ในที่เดียว สร้าง Context ใน Organization Settings เพิ่มตัวแปรของคุณที่นั่น จากนั้นอ้างอิงถึงมัน:

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apidog-secrets

ตอนนี้ job จะอ่าน APIDOG_ACCESS_TOKEN และส่วนที่เหลือจาก Context apidog-secrets หมุนเวียนโทเค็นเพียงครั้งเดียว และทุกโปรเจกต์จะได้รับค่าใหม่

การรันแบบ Data-driven และตัวเลือกอื่นๆ

CLI มีแฟล็กมากกว่าที่คู่มือนี้ใช้ สองแฟล็กนี้มีประโยชน์สำหรับ CI

คุณสามารถทำซ้ำสถานการณ์จำลองผ่านแถวข้อมูลการทดสอบได้ด้วย -d และ -n:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -d ./data/users.csv \
  -r cli,junit \
  --out-dir ./reports

แฟล็ก -d ใช้พาธไฟล์ CSV หรือ JSON หรือ ID ชุดข้อมูลที่เก็บไว้แบบตัวเลข และรันสถานการณ์จำลองหนึ่งครั้งต่อแถว คู่มือการทดสอบแบบ data-driven แสดงวิธีการจัดโครงสร้างไฟล์เหล่านั้น

คุณยังสามารถควบคุมวิธีการจัดการความล้มเหลวของการรันด้วย --on-error ซึ่งรับค่า continue, end หรือ ignore และสำหรับโปรเจกต์ที่ใช้ Apidog branches, --project <id> --branch <name> จะกำหนดเป้าหมายไปที่ branch เฉพาะ หากต้องการพุชภาพรวมรายงานไปยัง Apidog cloud ให้เพิ่ม --upload-report เป็นแฟล็กเปล่า

สิ่งนี้เข้ากับเวิร์กโฟลว์ของ Apidog ได้อย่างไร

ประเด็นสำคัญของ Apidog CLI คือคุณไม่ต้องเขียนหรือดูแลรักษาโค้ดทดสอบ คุณสร้าง สถานการณ์จำลองการทดสอบจากบรรทัดคำสั่ง หรือในตัวสร้างการทดสอบแบบภาพ กำหนด assertions บนสถานะโค้ดและเนื้อหาการตอบกลับ และบันทึกมัน จากนั้น CI จะรันสถานการณ์จำลองนั้นอย่างแม่นยำ

เนื่องจากสถานการณ์จำลองอยู่ในโปรเจกต์ Apidog ของคุณ ทีมของคุณจึงแก้ไขการทดสอบในที่เดียว การกำหนดค่า CI ไม่ค่อยมีการเปลี่ยนแปลง; มันเพียงแค่เรียกใช้ apidog run เมื่อมีคนเพิ่ม assertion ในแอป บิลด์ CircleCI ถัดไปก็จะนำไปใช้โดยไม่ต้องแก้ไข YAML

นั่นทำให้เกิดการแบ่งแยกที่ชัดเจน Apidog เป็นเจ้าของสิ่งที่ถูกทดสอบ CircleCI เป็นเจ้าของเวลาและสถานที่ที่มันทำงาน หากคุณต้องการเปรียบเทียบ CircleCI กับ runner อื่นๆ สำหรับงานประเภทนี้ บทสรุปของ เครื่องมือ Continuous Integration สำหรับทีม API จะอธิบายถึงข้อดีข้อเสีย

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

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

CircleCI คืออะไร?

CircleCI คือแพลตฟอร์ม Continuous Integration และ Delivery บนคลาวด์ มันเชื่อมต่อกับ Git repository ของคุณ อ่านไฟล์ .circleci/config.yml และรันขั้นตอนการสร้าง (build), การทดสอบ (test) และการปรับใช้ (deploy) โดยอัตโนมัติทุกครั้งที่คุณพุชโค้ด ซึ่งช่วยลดความจำเป็นในการรันขั้นตอนเหล่านั้นด้วยตนเองบนเครื่องของคุณ

CircleCI ใช้สำหรับอะไร?

ทีมต่างๆ ใช้ CircleCI เพื่อทำให้การทดสอบและการปรับใช้เป็นไปโดยอัตโนมัติ งานทั่วไปได้แก่ การคอมไพล์โค้ด การรัน unit และ integration tests การตรวจสอบสัญญา API การสร้าง Docker images และการส่งมอบรีลีสไปยัง staging หรือ production ในคู่มือนี้ งานที่กล่าวถึงคือการรัน Apidog CLI API tests ทุกครั้งที่มีการพุช

CircleCI ฟรีหรือไม่?

CircleCI มีแผนบริการฟรีที่รวมเครดิตการสร้างรายเดือน ซึ่งเพียงพอสำหรับโปรเจกต์ขนาดเล็กและ personal repo ทีมขนาดใหญ่ที่ต้องการความพร้อมกัน (concurrency) มากขึ้น นาทีการสร้างที่ยาวนานขึ้น หรือเครื่องที่ใหญ่ขึ้น จะเปลี่ยนไปใช้แผน Performance และ Scale แบบชำระเงิน ตรวจสอบหน้าการกำหนดราคาปัจจุบันของ CircleCI สำหรับขีดจำกัดที่แน่นอน

CircleCI เป็นโอเพนซอร์สหรือไม่?

ไม่ CircleCI เป็นผลิตภัณฑ์เชิงพาณิชย์ที่โฮสต์ ไม่ใช่โอเพนซอร์ส คุณกำหนดค่าผ่านไฟล์ YAML และรันบนโครงสร้างพื้นฐานของ CircleCI หรือ self-hosted runner หากคุณต้องการเซิร์ฟเวอร์ CI แบบโอเพนซอร์สเต็มรูปแบบ Jenkins เป็นทางเลือกทั่วไป ซึ่งมีการกล่าวถึงในการเปรียบเทียบ CircleCI กับ Jenkins

CircleCI ทำงานอย่างไร?

เมื่อคุณพุชคอมมิต CircleCI จะตรวจจับการเปลี่ยนแปลง อ่านไฟล์ .circleci/config.yml และเปิดใช้งาน executor ที่คุณกำหนดไว้ เช่น คอนเทนเนอร์ Docker cimg/node มันจะรันแต่ละขั้นตอนใน job ของคุณตามลำดับ จากนั้นรายงานผลลัพธ์กลับไปยัง Git provider ของคุณ เวิร์กโฟลว์ช่วยให้คุณสามารถเชื่อมโยงและรัน job แบบขนานได้ สำหรับภาพรวมที่ใหญ่ขึ้นว่าสิ่งนี้เข้ากับ delivery pipeline ได้อย่างไร โปรดดู คู่มือ CI/CD คืออะไร