วิธีรัน Apidog CLI API Tests ใน Drone CI

คุณสามารถรันการทดสอบ Apidog CLI API ใน Drone CI ได้โดยเพิ่มขั้นตอน Docker pipeline ที่ใช้ Node image ติดตั้ง apidog-cli และรัน apidog run กับสภาพแวดล้อม โทเค็นการเข้าถึง Apidog ของคุณจะถูกเก็บไว้ใน Drone secret และถูกฉีดเข้าไปผ่าน from_secret คู่มือนี้จะแนะนำการคัดลอกและวาง .drone.yml การจัดการ secret การควบคุมสาขา และวิธีการเปิดเผยรายงานการทดสอบเนื่องจาก Drone ไม่มีที่เก็บ artifacts ในตัว

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

Drone คือแพลตฟอร์ม CI/CD แบบโอเพนซอร์สที่ใช้คอนเทนเนอร์เป็นหลัก ซึ่งปัจจุบันเป็นส่วนหนึ่งของ Harness CI/CD ย่อมาจาก continuous integration และ continuous delivery ซึ่งเป็นแนวทางปฏิบัติในการสร้างและทดสอบโค้ดโดยอัตโนมัติทุกครั้งที่มีการเปลี่ยนแปลง หากคุณต้องการทบทวนแนวคิดนี้ โปรดดู CI/CD คืออะไร

คุณสมบัติที่สำคัญของ Drone นั้นเรียบง่าย: ทุกขั้นตอนของ Pipeline จะทำงานภายใน Docker container ของตัวเอง ไม่มี build agent ที่ใช้ร่วมกันซึ่งมีเครื่องมือที่ติดตั้งไว้ล่วงหน้ามากมาย คุณเลือก image สำหรับแต่ละขั้นตอน และ Drone จะรันคำสั่งของคุณภายในนั้น ซึ่งทำให้การ build สามารถทำซ้ำได้และเข้าใจง่าย

คุณกำหนด pipeline ในไฟล์ .drone.yml ที่รูทของ repository ของคุณ Docker pipeline มีคีย์หลักสามคีย์: kind, type และ name การทำงานเกิดขึ้นภายใต้ steps ซึ่งแต่ละขั้นตอนจะประกาศ name, image และรายการ commands

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world

Drone รัน commands เป็นสคริปต์เชลล์ด้วย set -e และ set -x ดังนั้นการ build จะล้มเหลวอย่างรวดเร็วที่ exit code แรกที่ไม่ใช่ศูนย์ และจะแสดงคำสั่งแต่ละคำสั่งก่อนที่จะรัน คำสั่งจะแทนที่ container entrypoint และไดเรกทอรีการทำงานคือรูทของ repository ของคุณ

ทำไมต้องรันการทดสอบ API ในขั้นตอนคอนเทนเนอร์

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

Apidog เข้ากับโมเดลนี้ได้ดี คุณสร้างและดูแลการทดสอบของคุณด้วยภาพในแอป Apidog จากนั้นรันสถานการณ์การทดสอบเดียวกันจากบรรทัดคำสั่งด้วย Apidog CLI ไม่ต้องเขียนสคริปต์ใหม่ ไม่ต้องมีชุดทดสอบแยกต่างหาก สำหรับคำแนะนำเพิ่มเติมเกี่ยวกับการรวมการทดสอบ API เข้ากับ pipelines โปรดอ่าน แนวทางปฏิบัติที่ดีที่สุดของ CI/CD สำหรับการทดสอบ API

Apidog เป็นแพลตฟอร์ม API แบบ all-in-one สำหรับการออกแบบ การดีบัก การทดสอบ การจำลอง และการจัดทำเอกสาร CLI คือส่วนที่เปลี่ยนสถานการณ์การทดสอบที่คุณบันทึกไว้ให้เป็นคำสั่งเดียวที่สามารถทำซ้ำได้ ซึ่งเป็นสิ่งที่ขั้นตอน Drone ต้องการอย่างแท้จริง

คำสั่ง Apidog CLI ที่คุณจะรัน

ติดตั้ง CLI ด้วย npm จากนั้นรันสถานการณ์การทดสอบ ใน CI คุณจะชี้การรันไปยังสถานการณ์ที่บันทึกไว้พร้อมกับ flag ดังนั้นจึงไม่มีไฟล์ collection ภายในเครื่องให้จัดการ

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

นี่คือสิ่งที่แต่ละ flag ทำงาน:

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

คุณสามารถเพิ่ม flag เพิ่มเติมได้ตามต้องการ:

• -n หรือ --iteration-count ทำซ้ำการรันตามจำนวนครั้งที่กำหนด
• -d หรือ --iteration-data รับพาธไฟล์ CSV หรือ JSON หรือ ID ชุดข้อมูลที่เก็บไว้สำหรับ data-driven runs
• --out-dir กำหนดไดเรกทอรีเอาต์พุตรีพอร์ต
• --upload-report อัปโหลดภาพรวมรายงานไปยัง Apidog cloud ซึ่งคุณสามารถดูได้ในแอป คุณสามารถใช้เป็น flag เปล่าได้
• --on-error ควบคุมพฤติกรรมความล้มเหลวด้วย continue, end หรือ ignore
• --project <id> และ --branch <name> กำหนดเป้าหมายสาขาโปรเจกต์ที่เฉพาะเจาะจง

สำหรับการดูคำสั่งและตัวเลือกทั้งหมด โปรดดู คู่มือ Apidog CLI ฉบับสมบูรณ์ และคำแนะนำเกี่ยวกับการ ทดสอบ REST API จากบรรทัดคำสั่ง

ไฟล์ .drone.yml ที่สมบูรณ์สำหรับการทดสอบ Apidog

นี่คือ pipeline ที่ใช้งานได้ มันใช้ Node image ติดตั้ง CLI และรันสถานการณ์ของคุณ โทเค็นมาจาก Drone secret แทนที่จะเป็น hardcoded

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

แทนที่ 1234567 ด้วย ID สถานการณ์การทดสอบของคุณ และ 89012 ด้วย ID สภาพแวดล้อมของคุณ ทั้งสองสามารถมองเห็นได้ในแอป Apidog เนื่องจากขั้นตอนนี้ใช้ cli reporter รายละเอียดการผ่าน/ไม่ผ่านทั้งหมดจะพิมพ์ลงในบันทึกการ build ของ Drone โดยตรง ซึ่งใครก็ตามที่ตรวจสอบการ build ก็สามารถอ่านได้

การจัดเก็บ Secrets ใน Drone CI

อย่าคอมมิต API token ไปยัง repository ของคุณ Drone จะเก็บ secrets ออกจาก YAML และฉีดเข้าไปเมื่อรันไทม์

คุณอ้างอิง secret ภายในบล็อก environment ของขั้นตอน (หรือบล็อก settings ของปลั๊กอิน) ด้วย from_secret ค่าที่คุณเขียนคือชื่อของ secret ไม่ใช่โทเค็นเอง

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token

มีสองวิธีทั่วไปในการสร้าง secret วิธีแรกคือ Drone UI: เปิด repository ของคุณ ไปที่ Settings จากนั้น Secrets และเพิ่ม secret ที่ชื่อ apidog_access_token โดยใช้โทเค็นของคุณเป็นค่า วิธีที่สองคือเครื่องมือ command-line ของ Drone

drone secret add \
  --repository your-org/your-repo \
  --name apidog_access_token \
  --data your-apidog-token

ยืนยันชื่อ flag ที่แน่นอนเทียบกับเอกสาร Drone CLI สำหรับเวอร์ชันของคุณ เนื่องจาก flag ของ CLI สามารถเปลี่ยนแปลงได้ระหว่างการเผยแพร่ Drone ยังรองรับรูปแบบ encrypted-secret ใน repository ที่ drone encrypt สร้าง encrypted blob ที่คุณฝังเป็นเอกสาร YAML แบบ kind: secret แยกต่างหาก สำหรับทีมส่วนใหญ่ การใช้ repo secrets ที่เพิ่มผ่าน UI หรือ drone secret add นั้นง่ายกว่าและเป็นจุดเริ่มต้นที่แนะนำ

การเก็บโทเค็นไว้ใน secret เป็นหลักปฏิบัติเดียวกับที่คุณจะใช้ที่อื่น สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีที่ CLI จัดการข้อมูลประจำตัว โปรดดูคู่มือ การยืนยันตัวตน Apidog CLI

การควบคุมการรันตาม Branch และ Event

Drone มีสองกลไกในการควบคุมว่าการทำงานจะรันเมื่อใด: trigger ที่ระดับ pipeline และ when ที่ระดับ step

บล็อก trigger จะตัดสินใจว่า pipeline ทั้งหมดจะรันหรือไม่ เงื่อนไขทั้งหมดจะต้องเป็นจริง ดังนั้นตัวอย่างด้านล่างจะรันเฉพาะเมื่อมีการพุชและ pull request ที่กำหนดเป้าหมายไปที่ main

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

บล็อก when จะอยู่ภายในขั้นตอนเดียวและควบคุมเฉพาะขั้นตอนนั้น สิ่งนี้มีประโยชน์เมื่อคุณต้องการให้ pipeline ส่วนใหญ่รันในทุกที่ แต่สงวนการทดสอบที่หนักกว่าไว้สำหรับ branch เดียว

steps:
  - name: run-api-tests
    image: node:20-alpine
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
    when:
      branch:
        - main
      event:
        - push

ทั้งสองบล็อกรองรับรูปแบบ glob และ sub-key สำหรับการรวม/ไม่รวม ประเภท event ที่รองรับ ได้แก่ push, pull_request, tag, promote, rollback, cron และ custom

การเปิดเผยรายงานการทดสอบโดยไม่มีที่เก็บ Artifact

Drone ไม่มีบริการโฮสต์ artifact ในตัว ซึ่งเปลี่ยนวิธีที่คุณจัดการรายงาน แต่คุณมีสองทางเลือกที่ชัดเจน

วิธีแรกคือวิธีที่ง่ายที่สุด: ใช้ cli reporter เพื่อให้ผลลัพธ์พิมพ์ลงในบันทึกการ build สำหรับทีมส่วนใหญ่ วิธีนี้ก็เพียงพอแล้ว เนื่องจากบันทึกจะแสดงอยู่แล้วว่า assertion ใดผ่านและใดล้มเหลว

ตัวเลือกที่สองคือการสร้างรายงาน HTML และอัปโหลดไปยังที่จัดเก็บที่ทนทาน Drone เผยแพร่ปลั๊กอิน S3 อย่างเป็นทางการ คือ plugins/s3 ซึ่งจะอัปโหลดไฟล์ไปยัง S3 หรือที่จัดเก็บที่เข้ากันได้กับ S3 สร้างรายงานด้วย html reporter และ --out-dir จากนั้นเพิ่มขั้นตอนการอัปโหลด

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports

  - name: upload-report
    image: plugins/s3
    settings:
      bucket: my-bucket
      region: us-east-1
      source: reports/**/*
      target: /apidog-reports
      access_key:
        from_secret: aws_access_key
      secret_key:
        from_secret: aws_secret_key

ปลั๊กอินอ่านข้อมูลรับรอง AWS จาก secrets ผ่าน from_secret ซึ่งเป็นกลไกเดียวกับที่คุณใช้สำหรับโทเค็น Apidog คีย์ source คือ glob ของไฟล์ที่จะอัปโหลด และ target คือคำนำหน้าปลายทางใน bucket

หากคุณต้องการดูรายละเอียดเพิ่มเติมเกี่ยวกับสิ่งที่รายงานประกอบด้วยและวิธีการอ่าน โปรดดูการวิเคราะห์ รายงานการทดสอบ Apidog CLI

การเพิ่ม Data-Driven Runs

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

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli

แต่ละแถวใน data.csv จะกลายเป็นหนึ่ง iteration โดยมีค่าคอลัมน์ผูกกับตัวแปรสถานการณ์ของคุณ รูปแบบเต็มครอบคลุมอยู่ใน การทดสอบที่ขับเคลื่อนด้วยข้อมูลของ Apidog CLI

เปรียบเทียบกับเครื่องมือ CI อื่นๆ

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

หากคุณรัน pipelines ที่อื่นด้วย Apidog ก็มีคำแนะนำที่สอดคล้องกันสำหรับ GitHub Actions และ Azure Pipelines แนวคิดร่วมกันคือการทดสอบของคุณอยู่ใน Apidog และเครื่องมือ CI เพียงแค่เรียกใช้การทดสอบเหล่านั้น

ข้อสังเกตอย่างตรงไปตรงมาเกี่ยวกับขอบเขต: Apidog CLI รันการทดสอบฟังก์ชันและสัญญา ไม่ใช่การทดสอบโหลดขนาดใหญ่ หากคุณต้องการผู้ใช้เสมือนพร้อมกันหลายพันคนเพื่อทดสอบ endpoint ให้ใช้เครื่องมือทดสอบโหลดโดยเฉพาะ สำหรับการตรวจสอบว่า API ของคุณทำงานถูกต้องทุกครั้งที่คอมมิต CLI ในขั้นตอน Drone ทำงานได้ดี

สร้างการทดสอบด้วยภาพ, รันด้วยคำสั่งเดียว

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

จากนั้น CI จะรันชุดการทดสอบเดียวกันนั้นด้วยคำสั่ง CLI เพียงคำสั่งเดียวภายในขั้นตอนคอนเทนเนอร์ เมื่อเพื่อนร่วมทีมอัปเดตการทดสอบในแอป Apidog การ build ของ Drone ครั้งถัดไปจะรับการเปลี่ยนแปลงนั้นโดยอัตโนมัติ ไม่มีการสำเนาการทดสอบชุดที่สองที่ต้องคอยซิงค์

ดาวน์โหลด Apidog ฟรี เพื่อสร้างสถานการณ์การทดสอบแรกของคุณ จากนั้นนำ .drone.yml ด้านบนไปใส่ใน repository ของคุณเพื่อรันทุกครั้งที่มีการพุช

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

Drone CI คืออะไร?

Drone คือแพลตฟอร์ม CI/CD แบบโอเพนซอร์สที่ใช้คอนเทนเนอร์เป็นหลัก ซึ่งปัจจุบันเป็นส่วนหนึ่งของ Harness มันรันทุกขั้นตอนของ pipeline ภายใน Docker container ของตัวเอง โดยที่ pipelines ถูกกำหนดไว้ในไฟล์ .drone.yml สิ่งนี้ช่วยให้การ build สามารถทำซ้ำได้และหลีกเลี่ยงการติดตั้งเครื่องมือมากมายของ build agent แบบดั้งเดิม

Drone CI ฟรีหรือไม่?

โปรเจกต์หลักของ Drone เป็นโอเพนซอร์สและฟรีสำหรับการโฮสต์ด้วยตนเอง หลังจากที่ Harness เข้าซื้อกิจการ Drone ก็กลายเป็น Harness CI Community Edition โดยมีรุ่น enterprise แบบชำระเงินให้เลือกใช้ สำหรับทีมส่วนใหญ่ เวอร์ชันโอเพนซอร์สที่โฮสต์ด้วยตนเองก็ครอบคลุมการรันการทดสอบ API เช่นเดียวกับในคู่มือนี้

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

ใช่ Drone เป็นหนึ่งในเครื่องมือ CI แบบ container-native ดั้งเดิมและยังคงเป็นโอเพนซอร์ส เมื่อ Harness เข้าซื้อกิจการในปี 2020 บริษัทได้ให้คำมั่นที่จะรักษาโปรเจกต์ให้เป็นโอเพนซอร์ส และคุณยังคงสามารถโฮสต์ด้วยตนเองได้

Drone CI ใช้งานอย่างไร?

ทีมใช้ Drone เพื่อสร้าง ทดสอบ และส่งมอบโค้ดโดยอัตโนมัติทุกครั้งที่มีการพุชหรือ pull request คุณคอมมิตไฟล์ .drone.yml ไปยัง repository ของคุณ Drone จะอ่านไฟล์นั้นและรันแต่ละขั้นตอนในคอนเทนเนอร์ ขั้นตอนทั่วไปได้แก่ การคอมไพล์โค้ด การรัน unit tests การรัน API tests และการอัปโหลด artifacts ไปยังที่จัดเก็บภายนอก

คุณจัดเก็บ secrets ใน Drone CI ได้อย่างไร?

คุณเพิ่ม secrets ผ่านหน้า Settings จากนั้น Secrets ใน Drone UI ของ repository หรือด้วย drone secret add จาก CLI จากนั้นคุณอ้างอิงแต่ละ secret ภายในบล็อก environment ของขั้นตอนหรือบล็อก settings ของปลั๊กอินโดยใช้ from_secret ซึ่งค่าคือชื่อของ secret ตัวโทเค็นเองจะไม่ปรากฏใน YAML ของคุณ

ฉันสามารถรันการทดสอบ Apidog ใน CI โดยไม่ต้องเขียนสคริปต์ได้หรือไม่?

ใช่ คุณสร้างสถานการณ์การทดสอบด้วยภาพในแอป Apidog จากนั้นรันใน CI ด้วยคำสั่ง apidog run เพียงคำสั่งเดียว ขั้นตอน Drone ต้องการเพียง Node image, บรรทัด npm install -g apidog-cli และคำสั่งรันที่ชี้ไปที่ ID สถานการณ์และสภาพแวดล้อมของคุณ