วิธีทดสอบ API อัตโนมัติบน Buildkite

คุณสามารถรันการทดสอบ API แบบอัตโนมัติใน Buildkite ได้ด้วยไฟล์ .buildkite/pipeline.yml: ติดตั้ง Apidog CLI, รัน apidog run ด้วย environment ที่ต้องการ, ส่ง Apidog access token ผ่าน Buildkite secrets และอัปโหลดรายงาน HTML เป็น build artifact เพื่อให้ทีมตรวจสอบผลลัพธ์ย้อนหลังได้

ลองใช้ Apidog วันนี้

ก่อนเริ่ม ให้แยกให้ชัดว่า Buildkite คือแพลตฟอร์ม CI/CD ไม่ใช่ Docker BuildKit ซึ่งเป็น backend สำหรับ build Docker image บทความนี้พูดถึง Buildkite CI/CD เท่านั้น

Buildkite คืออะไร

Buildkite เป็นแพลตฟอร์ม CI/CD แบบไฮบริด มี control plane ที่โฮสต์โดย Buildkite สำหรับ dashboard และการจัดการ build ส่วนงานจริงจะถูกรันโดย agent

รูปแบบนี้ทำให้คุณเลือกได้ว่าจะรัน agent บน infrastructure ของตัวเอง หรือใช้ Buildkite-hosted agents ที่ Buildkite จัดการ compute ให้

สำหรับทีม API จุดสำคัญคือคุณสามารถรัน test ใน network ที่เข้าถึง staging, test service, internal endpoint หรือ dependency ภายในองค์กรได้โดยตรง ขณะที่ Buildkite ทำหน้าที่ orchestrate pipeline

Buildkite agent เป็นโอเพนซอร์ส เขียนด้วย Go และเผยแพร่ภายใต้ MIT License ส่วน control plane และ platform รอบ ๆ เป็นผลิตภัณฑ์ SaaS เชิงพาณิชย์

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

ทีมมักใช้ Buildkite เพื่อ automate งานที่เกิดจาก code change เช่น

• build artifact
• run unit test และ integration test
• deploy service
• run end-to-end check
• gate production deployment ด้วย automated test

สำหรับ API testing คุณสามารถให้ Buildkite รันชุดทดสอบกับ staging หรือ production-like environment แล้วหยุด deployment เมื่อ contract หรือ response validation ล้มเหลว

ถ้าคุณกำลังเปรียบเทียบ Buildkite กับ CI/CD ตัวอื่น ดูบทสรุปนี้ได้: เครื่องมือ Continuous Integration ที่ดีที่สุดสำหรับทีม API

วิธีการกำหนด Buildkite pipeline

Buildkite pipeline ปกติจะอยู่ที่:

.buildkite/pipeline.yml

เมื่อ build เริ่มทำงาน Buildkite จะอ่านไฟล์นี้และ execute ตาม steps: ที่กำหนดไว้

ประเภท step ที่ใช้บ่อยสำหรับ API testing คือ:

• Command step: รัน shell command บน agent ใช้สำหรับติดตั้ง CLI และรัน test
• Wait step: รอให้ step ก่อนหน้าทั้งหมดจบก่อน ใช้ - wait
• Block step: รอ manual approval ใช้ - block: "Label" เหมาะก่อน deploy production

ตัวอย่างโครงสร้างพื้นฐาน:

steps:
  - label: ":test_tube: API tests"
    command: "echo run tests here"

  - wait

  - block: ":rocket: Deploy?"

  - label: ":rocket: Deploy"
    command: "scripts/deploy.sh"

คีย์ที่มักใช้ใน command step:

• label: ชื่อ step ที่แสดงใน UI
• key: ID สำหรับอ้างอิง step
• command หรือ commands: คำสั่ง shell
• env: environment variables ที่ไม่ใช่ข้อมูลลับ
• agents: target agent ด้วย tag เช่น queue
• secrets: inject secret เป็น environment variable
• artifact_paths: path ของไฟล์ที่ต้องเก็บเป็น artifact
• parallelism: กระจายงานเดียวกันเป็นหลาย job
• matrix: รัน step เดียวกันกับหลายค่า เช่น หลาย environment

ตัวอย่างการกำหนด agent queue:

agents:
  queue: "tests"

ใช้ tag/queue เพื่อให้ API test ไปรันบน agent ที่มี network access และ tooling ถูกต้อง

Pipeline แบบคัดลอกไปใช้ได้ทันทีสำหรับรัน API test

สร้างไฟล์ .buildkite/pipeline.yml:

steps:
  - label: ":test_tube: API tests (Apidog)"
    key: "api-tests"
    command: |
      npm install -g apidog-cli
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    agents:
      queue: "default"
    secrets:
      - APIDOG_ACCESS_TOKEN

สิ่งที่ pipeline นี้ทำ:

1. ติดตั้ง Apidog CLI ด้วย npm install -g apidog-cli
2. รัน test scenario ด้วย apidog run
3. ใช้ access token จาก Buildkite secret
4. สร้างรายงานทั้งแบบ CLI และ HTML
5. อัปโหลด HTML report เป็น Buildkite artifact

ความหมายของ flag หลัก:

• --access-token "$APIDOG_ACCESS_TOKEN": token สำหรับให้ CLI เข้าถึงโปรเจกต์ Apidog
• -t 637132: ID ของ test scenario หรือ scenario folder
• -e 358171: runtime environment ID เช่น staging หรือ production
• -r html,cli: สร้างทั้ง terminal summary และ HTML report

บน Buildkite agent จะมี buildkite-agent binary พร้อมใช้งานอยู่แล้ว คุณต้องติดตั้งเฉพาะ apidog-cli

อ่านรายละเอียด flag เพิ่มเติมได้ที่ คู่มือ Apidog CLI ฉบับสมบูรณ์

ถ้าต้องการทดลองรันจาก local terminal ก่อนนำเข้า CI ดูตัวอย่างได้ที่ บทช่วยสอนการทดสอบ Apidog CLI ด้วยบรรทัดคำสั่ง

การส่ง Apidog access token ด้วย Buildkite secrets

อย่าใส่ Apidog access token ลงใน pipeline.yml โดยตรง และอย่า echo token ออก log ให้ใช้ Buildkite secrets แทน

Buildkite secrets เป็น encrypted key-value store ที่รองรับทั้ง Buildkite-hosted agents และ self-hosted agents ค่า secret จะถูก mask ใน log โดยอัตโนมัติหากปรากฏออกมา

วิธีที่ 1: ใช้ secrets: ใน command step

ถ้าชื่อ secret และชื่อ environment variable เหมือนกัน:

steps:
  - command: |
      apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
    secrets:
      - APIDOG_ACCESS_TOKEN

ถ้าชื่อ secret ใน Buildkite ต่างจากชื่อ environment variable ที่ต้องการใช้:

steps:
  - command: |
      apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
    secrets:
      APIDOG_ACCESS_TOKEN: apidog_token

ในตัวอย่างนี้:

• APIDOG_ACCESS_TOKEN คือชื่อ environment variable ใน job
• apidog_token คือ key ของ secret ใน Buildkite

วิธีที่ 2: ดึง secret ด้วย buildkite-agent secret get

ถ้าต้องการควบคุมใน script เอง:

APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli

บน self-hosted agents คุณยังสามารถใช้ environment agent hook หรือดึง secret จาก external store เช่น AWS Secrets Manager, HashiCorp Vault หรือ GCP ผ่าน Buildkite plugins ได้

ใช้ env: เฉพาะ configuration ที่ไม่ sensitive เท่านั้น เช่น environment name หรือ feature flag ห้ามใส่ token ลงไป

อ่านเพิ่มเรื่อง authentication ได้ที่ การยืนยันตัวตน Apidog CLI

การอัปโหลด HTML report เป็น artifact

เมื่อใช้ reporter -r html Apidog CLI จะสร้าง HTML report ใน workspace ของ agent ไฟล์นี้จะหายไปเมื่อ job จบ ถ้าไม่เก็บเป็น artifact

ใช้คำสั่งนี้หลัง apidog run:

buildkite-agent artifact upload "apidog-reports/**/*"

ควรใส่ quote รอบ glob pattern เพื่อไม่ให้ shell expand ก่อน ให้ buildkite-agent เป็นตัวจับคู่ไฟล์เอง

โดยค่าเริ่มต้น artifact จะถูกเก็บใน storage ที่ Buildkite จัดการ มี retention 6 เดือน และจำกัดขนาด 5GB ต่อ artifact หลัง build เสร็จ รายงานจะอยู่ในแท็บ Artifacts ของ build นั้น

ถ้าต้องการเข้าใจ output แต่ละแบบ ดู คู่มือรายงานการทดสอบ Apidog CLI

การรัน test พร้อมกันในหลาย environment

ถ้าต้องการรัน test scenario เดียวกันกับหลาย Apidog environment ให้ใช้ matrix

steps:
  - label: ":test_tube: API tests {{matrix.env}}"
    command: |
      npm install -g apidog-cli
      apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e "{{matrix.env}}" -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    secrets:
      - APIDOG_ACCESS_TOKEN
    matrix:
      setup:
        env:
          - "358171"   # staging environment id
          - "358172"   # production environment id

Buildkite จะสร้าง job แยกตามค่าใน matrix และแทนค่า {{matrix.env}} ในทั้ง label และคำสั่ง apidog run

ใช้ matrix เมื่อค่าที่รันแตกต่างกัน เช่น environment ID

ใช้ parallelism เมื่ออยากกระจายงานเดียวกันหลายชุด เช่น:

parallelism: 5

สำหรับ data-driven testing ที่ scenario เดียวอ่านหลายแถวจาก CSV หรือ JSON ให้ใช้ flag -d ของ Apidog CLI แทน Buildkite matrix ดูตัวอย่างได้ที่ คู่มือการทดสอบที่ขับเคลื่อนด้วยข้อมูลของ Apidog CLI

การจำกัด deployment ด้วย API test

รูปแบบที่ใช้บ่อย:

1. รัน API test
2. รอให้ test จบ
3. ขอ manual approval
4. deploy

ตัวอย่าง pipeline:

steps:
  - label: ":test_tube: API tests"
    command: "npm install -g apidog-cli && apidog run --access-token \"$APIDOG_ACCESS_TOKEN\" -t 637132 -e 358171 -r html,cli"
    secrets:
      - APIDOG_ACCESS_TOKEN

  - wait

  - block: ":rocket: Deploy?"
    branches: "main"

  - label: ":rocket: Deploy"
    command: "scripts/deploy.sh"

การทำงาน:

• wait ทำให้ pipeline รอจน API test เสร็จ
• block หยุดรอ manual approval
• branches: "main" จำกัด approval step เฉพาะ branch main
• deploy จะรันต่อเมื่อมีคน approve เท่านั้น

วิธีนี้ช่วยป้องกันไม่ให้ build ที่ API test ล้มเหลวถูก deploy ไป production

อ่าน pattern เพิ่มเติมได้ที่ แนวทางปฏิบัติที่ดีที่สุดของ CI/CD สำหรับการทดสอบ API

การเพิ่ม annotation สรุปผลใน Buildkite

Build log มักยาวและไล่อ่านยาก คุณสามารถเพิ่ม summary บนหน้า build ด้วย buildkite-agent annotate

cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### API test results
All Apidog scenarios passed. [Download the full HTML report](artifact://apidog-reports/index.html)
EOF

ค่า --style ที่ใช้ได้ เช่น:

• info
• warning
• error
• success

ค่า --context เป็น ID ของ annotation ถ้า step ถัดไปใช้ context เดิม ระบบจะอัปเดต annotation เดิมแทนการเพิ่มรายการใหม่

ลิงก์ artifact:// ใช้ชี้ไปยัง artifact ที่อัปโหลดไว้ เช่น HTML report

Apidog เข้ากับ Buildkite อย่างไร

Pipeline ด้านบนตั้งใจให้สั้น เพราะ logic การทดสอบหลักอยู่ใน Apidog ไม่ใช่ใน YAML

Apidog เป็นแพลตฟอร์ม API แบบครบวงจรสำหรับออกแบบ, debug, test, mock และทำเอกสาร API คุณสร้าง test scenario ผ่าน visual editor, chain request, ส่งค่าระหว่าง step และเพิ่ม assertion ได้โดยไม่ต้องเขียน script จำนวนมาก

CLI คือส่วนที่เชื่อม Apidog เข้ากับ CI/CD คุณสร้าง scenario ใน Apidog ครั้งเดียว จากนั้นใช้ scenario ID และ environment ID ในคำสั่ง:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html

เมื่อทีมอัปเดต scenario ใน Apidog การรัน Buildkite ครั้งถัดไปจะใช้ test ล่าสุดโดยไม่ต้องแก้ YAML

ดูการใช้คำสั่งเดียวกันใน CI/CD อื่นได้ที่ คู่มือ Apidog CLI CI/CD pipeline และ Apidog CLI กับ GitHub Actions

ถ้าต้องการทดลองก่อนใส่ CI ให้รันจากเครื่องตัวเอง:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html

จากนั้นนำคำสั่งเดียวกันไปใส่ใน Buildkite pipeline ของคุณ

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

Buildkite คืออะไร?

Buildkite เป็นแพลตฟอร์ม CI/CD แบบไฮบริด โดย control plane ที่โฮสต์อยู่จะจัดการ dashboard และ build ส่วน agent จะรันงานจริง Agent สามารถอยู่บน infrastructure ของคุณเองหรือบน Buildkite-hosted compute ได้ Buildkite ไม่เกี่ยวข้องกับ Docker BuildKit

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

ใช้ automate งานจาก code change เช่น build artifact, run test และ deploy service สำหรับทีม API สามารถใช้รัน automated API test กับ staging หรือ production environment และบล็อก deployment เมื่อ test ล้มเหลว

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

เฉพาะ Buildkite agent เป็นโอเพนซอร์ส เขียนด้วย Go และเผยแพร่ภายใต้ MIT License ส่วน platform และ control plane รอบ ๆ เป็น SaaS เชิงพาณิชย์

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

Buildkite มีแผนฟรีชื่อ Personal ไม่มีค่าใช้จ่าย ไม่ต้องใช้บัตรเครดิต และไม่มีวันหมดอายุ โดยรวมงานพร้อมกัน 3 งาน, ผู้ใช้ 1 คน, data retention 90 วัน, Buildkite-hosted agents บน Linux 500 นาทีต่อเดือน และ test executions 50,000 ครั้งต่อเดือน รวมถึง All Access trial 30 วันสำหรับประเมินฟีเจอร์แบบชำระเงิน

คุณอัปโหลด artifact ใน Buildkite ได้อย่างไร?

รันคำสั่งนี้ใน command step:

buildkite-agent artifact upload "<pattern>"

ตัวอย่างสำหรับ Apidog HTML report:

buildkite-agent artifact upload "apidog-reports/**/*"

ใส่ quote รอบ glob pattern เพื่อให้ Buildkite agent เป็นตัว match ไฟล์เอง ไม่ใช่ shell

คุณรัน API test ใน Buildkite pipeline ได้อย่างไร?

เพิ่ม command step ใน .buildkite/pipeline.yml เพื่อติดตั้ง Apidog CLI แล้วรัน apidog run พร้อม scenario ID, environment ID และ reporter ที่ต้องการ ตัวอย่าง:

steps:
  - label: ":test_tube: API tests (Apidog)"
    command: |
      npm install -g apidog-cli
      apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    secrets:
      - APIDOG_ACCESS_TOKEN

ส่ง token ผ่าน Buildkite secret และอัปโหลด HTML report เป็น artifact เพื่อให้ผลลัพธ์ยังอยู่หลัง build จบ