Thanawat Wongchai

Posted on Jun 22 • Originally published at apidog.com

วิธีรัน Apidog CLI API Tests ใน Harness CI/CD

คุณสามารถรันการทดสอบ Apidog CLI ใน Harness ได้ด้วย CI stage เพียงหนึ่ง stage: ติดตั้ง apidog-cli, รัน apidog run, และเผยแพร่ผลลัพธ์แบบ JUnit ให้ Harness อ่าน แนะนำให้เก็บ Apidog access token เป็น Harness secret แล้วอ้างอิงผ่าน <+secrets.getValue("...")> เพื่อไม่ให้โทเค็นหลุดใน YAML บทความนี้มีตัวอย่าง Pipeline YAML ที่คัดลอกไปใช้ได้ทั้ง Harness Cloud และ self-hosted delegate

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

Harness CI/CD คืออะไร?

Harness CI เป็นโมดูล Continuous Integration ของแพลตฟอร์ม Harness ใช้สำหรับ build, test และตรวจสอบโค้ดบนโครงสร้างพื้นฐานที่ Harness จัดการให้ หรือบนเครื่อง/คลัสเตอร์ที่คุณโฮสต์เอง จากนั้นส่ง artifacts ต่อให้ Harness CD สำหรับ deployment

ใน Harness คุณกำหนด pipeline เป็น YAML โดยทั่วไปประกอบด้วย:

pipeline: เก็บ metadata และรายการ stages
stage: แต่ละ stage มี type เช่น CI
spec: กำหนด build infrastructure และ execution
execution: เก็บลำดับ steps
step: หน่วยงานย่อย เช่น Run step สำหรับรัน shell command

สำหรับ API testing รูปแบบจะตรงไปตรงมา: เพิ่ม CI stage, เพิ่ม Run step เพื่อรัน Apidog CLI, แล้วให้ Harness ตัดสินผล build จาก exit code และ JUnit report ถ้าการทดสอบล้มเหลว step จะล้มเหลว และ pipeline จะหยุดตามเงื่อนไขปกติของ CI

Harness รองรับการอ่าน JUnit XML สำหรับรายงานผลทดสอบ ส่วน Apidog CLI สามารถสร้าง JUnit XML ได้ ทำให้คุณเห็นผลลัพธ์ในแท็บ Tests ของ Harness โดยไม่ต้องเขียน integration เพิ่ม

โครงสร้าง Run step สำหรับ Apidog CLI

Run step คือจุดที่คุณติดตั้งและรัน Apidog CLI โดย spec ของ Run step จะมีสองส่วนหลัก:

spec:
  shell: Sh
  command: |-
    npm install -g apidog-cli
    apidog run ...

ใช้ YAML block scalar |- เพื่อเขียนหลายคำสั่งใน step เดียวได้ ตัวอย่างในบทความนี้จะใช้แนวทางเดียวกันทั้งหมด:

ติดตั้ง CLI ด้วย npm
รัน test scenario จาก Apidog Cloud
สร้างรายงาน cli และ junit
ให้ Harness อ่านไฟล์ XML จาก apidog-reports/*.xml

Apidog CLI ในหนึ่งนาที

Apidog CLI เป็น command-line runner สำหรับ test scenario ที่คุณสร้างไว้ใน Apidog คุณออกแบบและดีบัก test ในแอป จากนั้นรันแบบ headless ใน CI/CD pipeline ได้ คล้ายกับการใช้ Newman กับ Postman collections หากต้องการเปรียบเทียบเพิ่มเติม ดู Apidog CLI กับ Newman

คำสั่งพื้นฐานสำหรับ CI คือ:

npm install -g apidog-cli

apidog run \
  --access-token <ACCESS_TOKEN> \
  -t <TEST_SCENARIO_ID> \
  -e <ENVIRONMENT_ID> \
  -r cli,junit \
  --out-dir ./apidog-reports

แฟล็กที่สำคัญ:

--access-token: ใช้ยืนยันตัวตนกับ Apidog Cloud ไม่มีรูปแบบย่อ
-t: ID ของ test scenario
-e: ID ของ environment จำเป็นต้องระบุ
-r: reporter ที่ต้องการ เช่น cli, html, json, junit
--out-dir: directory สำหรับบันทึกรายงาน ค่าเริ่มต้นคือ ./apidog-reports

สำหรับ Harness ให้ใช้ -r cli,junit เพื่อให้ CLI แสดงผลใน log และสร้าง JUnit XML ให้ Harness นำไปแสดงในแท็บ Tests ได้ อ่านรายละเอียดเพิ่มเติมได้ที่ รายงานการทดสอบ Apidog CLI

เก็บ Apidog access token เป็น Harness secret

อย่าฮาร์ดโค้ด token ใน pipeline YAML ให้สร้าง Harness secret ก่อน แล้วอ้างอิงจาก pipeline

ขั้นตอนใน Harness UI:

ไปที่ Project Settings หรือระดับ Org/Account ที่ต้องการ
เปิดเมนู Secrets
สร้าง Text secret ใหม่
ตั้ง identifier เช่น apidog_token
ใช้ identifier นี้ใน YAML

อ้างอิง secret ด้วย expression:

<+secrets.getValue("apidog_token")>

ถ้า secret อยู่ระดับ org หรือ account ให้ใส่ prefix:

<+secrets.getValue("org.apidog_token")>
<+secrets.getValue("account.apidog_token")>

ใน shell command แนะนำให้ครอบ expression ด้วย single quote เพื่อป้องกัน shell ขยายอักขระพิเศษ เช่น $ ภายใน token:

--access-token '<+secrets.getValue("apidog_token")>'

อ่านเพิ่มเติมเกี่ยวกับการตั้งค่า token ได้ใน คู่มือ Apidog CLI

Pipeline สำหรับ Harness Cloud

Harness Cloud เป็นจุดเริ่มต้นที่ง่ายที่สุด เพราะ Harness จัดการ build machine ให้ และมี Node.js/npm พร้อมใช้งานบน Linux runner ในตัวอย่างนี้ไม่ต้อง clone repository เพราะ test scenario อยู่ใน Apidog Cloud

ใช้ YAML นี้เป็น template:

pipeline:
  name: Apidog API Tests
  identifier: apidog_api_tests
  projectIdentifier: YOUR_PROJECT
  orgIdentifier: YOUR_ORG
  stages:
    - stage:
        name: API Tests
        identifier: api_tests
        type: CI
        spec:
          cloneCodebase: false
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 \
                        -e 1629989 \
                        -n 1 \
                        -r cli,junit \
                        --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

สิ่งที่ต้องเปลี่ยนก่อนใช้งาน:

YOUR_PROJECT: Harness project identifier
YOUR_ORG: Harness organization identifier
605067: ID ของ Apidog test scenario
1629989: ID ของ Apidog environment
apidog_token: identifier ของ Harness secret

แฟล็ก -n 1 หมายถึงรัน 1 iteration หากต้องการรันหลายรอบหรือใช้ data file ให้ปรับตามส่วน data-driven testing ด้านล่าง

เผยแพร่ผลการทดสอบใน Harness

ให้เพิ่มบล็อก reports ใน Run step เพื่อให้ Harness อ่าน JUnit XML:

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml

เงื่อนไขสำคัญคือคำสั่ง apidog run ต้องมี junit อยู่ใน reporter list:

-r cli,junit

ถ้าลืมใส่ junit CLI จะไม่สร้าง XML และแท็บ Tests ใน Harness จะว่าง แม้ step จะรันผ่านก็ตาม

หลัง pipeline จบ Harness จะ parse ไฟล์ที่ match กับ glob นี้:

apidog-reports/*.xml

แล้วแสดง test case, status และ duration ในหน้าผลลัพธ์ของ build

หมายเหตุ: Harness มี Test Intelligence สำหรับภาษาและ unit test บางประเภท โดยใช้ step ประเภท Test แต่สำหรับการนำเข้า report จาก Apidog CLI ให้ใช้ Run step พร้อม reports: JUnit ตามตัวอย่างนี้

Pipeline สำหรับ self-hosted delegate

ใช้ self-hosted delegate เมื่อคุณต้องการ:

เข้าถึง private/internal API
รันหลัง VPN หรือภายใน VPC
ควบคุม runtime เอง
ใช้ compute ของคุณเองแทน Harness Cloud build credits

บน Kubernetes delegate แต่ละ Run step จะรันใน container ดังนั้นต้องระบุ connectorRef และ image

ตัวอย่าง stage spec:

spec:
  cloneCodebase: false
  infrastructure:
    type: KubernetesDirect
    spec:
      connectorRef: YOUR_K8S_CONNECTOR
      namespace: harness-ci
  execution:
    steps:
      - step:
          type: Run
          name: Run Apidog CLI Tests
          identifier: run_apidog_cli_tests
          spec:
            connectorRef: YOUR_DOCKER_CONNECTOR
            image: node:20
            shell: Sh
            command: |-
              npm install -g apidog-cli
              apidog run \
                --access-token '<+secrets.getValue("apidog_token")>' \
                -t 605067 \
                -e 1629989 \
                -r cli,junit \
                --out-dir ./apidog-reports
            reports:
              type: JUnit
              spec:
                paths:
                  - apidog-reports/*.xml

สิ่งที่ต้องเปลี่ยน:

YOUR_K8S_CONNECTOR: Harness connector สำหรับ Kubernetes cluster
YOUR_DOCKER_CONNECTOR: Harness connector สำหรับดึง image
namespace: namespace ที่ delegate ใช้รัน CI pod
image: node:20: image ที่มี Node.js และ npm

อย่าผสมรูปแบบ infrastructure ใน stage เดียวกัน:

Harness Cloud ใช้ platform + runtime
Delegate-backed ใช้ infrastructure

เลือกอย่างใดอย่างหนึ่งต่อ stage

เลือกระหว่าง Harness Cloud กับ self-hosted delegate

เลือกตามตำแหน่งของ API และข้อกำหนดด้าน runtime

ปัจจัย	Harness Cloud	Self-hosted delegate
การตั้งค่า	ไม่ต้องดูแล infrastructure, npm พร้อมใช้งาน	คุณจัดการ cluster หรือ VM เอง
การเข้าถึงเครือข่าย	เหมาะกับ public endpoint	เหมาะกับ private/internal endpoint
Run step ต้องระบุ image	ไม่ต้อง	ต้องระบุบน Kubernetes infrastructure
ต้นทุน	ใช้ Harness Cloud build credits	ใช้ compute ของคุณเอง
เหมาะกับ	เริ่มต้นเร็ว, cloud API	internal API, custom runtime

แนวทางเลือก:

ถ้า API endpoint เข้าถึงได้จาก public internet ให้เริ่มด้วย Harness Cloud
ถ้า API อยู่หลัง VPN, firewall หรือ private network ให้ใช้ self-hosted delegate
ถ้าต้องการ runtime เฉพาะ ให้ใช้ delegate พร้อม custom Docker image

คำสั่ง apidog run แทบไม่ต่างกันระหว่างสองแบบ ต่างกันหลักๆ ที่ Harness infrastructure config เท่านั้น

การรันแบบ data-driven

ถ้า test scenario ต้องรันด้วยข้อมูลหลายชุด ให้ใช้ไฟล์ CSV หรือ JSON ผ่านแฟล็ก -d หรือ --iteration-data

apidog run \
  --access-token <ACCESS_TOKEN> \
  -t <TEST_SCENARIO_ID> \
  -e <ENVIRONMENT_ID> \
  -d ./data.csv \
  -n 5 \
  -r cli,junit \
  --out-dir ./apidog-reports

ใน Harness คุณต้องเตรียม data file ให้พร้อมก่อนรัน apidog run เช่น clone repository หรือสร้างไฟล์ใน step เดียวกัน

ตัวอย่างถ้าต้องใช้ไฟล์จาก repository:

spec:
  cloneCodebase: true
  platform:
    os: Linux
    arch: Amd64
  runtime:
    type: Cloud
    spec: {}
  execution:
    steps:
      - step:
          type: Run
          name: Run Apidog Data Driven Tests
          identifier: run_apidog_data_driven_tests
          spec:
            shell: Sh
            command: |-
              npm install -g apidog-cli
              apidog run \
                --access-token '<+secrets.getValue("apidog_token")>' \
                -t 605067 \
                -e 1629989 \
                -d ./test-data/data.csv \
                -n 5 \
                -r cli,junit \
                --out-dir ./apidog-reports
            reports:
              type: JUnit
              spec:
                paths:
                  - apidog-reports/*.xml

ดูรายละเอียดรูปแบบไฟล์ได้ที่ การทดสอบที่ขับเคลื่อนด้วยข้อมูลของ Apidog CLI และ การทดสอบ API แบบอัตโนมัติ

ทำไมต้องออกแบบ test scenario ใน Apidog ก่อน

CLI จะรัน test scenario ที่มีอยู่แล้วในโปรเจกต์ Apidog ของคุณ ดังนั้น workflow ที่แนะนำคือ:

ออกแบบ API และ request ใน Apidog
สร้าง test scenario ด้วย visual builder
เพิ่ม assertions และการเชื่อมค่าระหว่าง response/request
ดีบักจนผ่านใน Apidog
นำ scenario ID และ environment ID ไปใช้ใน Harness

Apidog เป็นแพลตฟอร์ม API แบบครบวงจรสำหรับ design, debug, test, mock และ documentation ทำให้ทีม backend และ QA ใช้แหล่งข้อมูลเดียวกันได้

เมื่อ test ผ่านใน Apidog แล้ว คำสั่ง apidog run ใน Harness จะรัน scenario เดียวกันแบบ headless ช่วยลดความต่างระหว่าง local/debug environment กับ CI environment

สำหรับแนวทาง CI/CD เพิ่มเติม อ่านได้ที่ CI/CD คืออะไร, คู่มือ GitHub Actions workflow และ การผสานรวมการทดสอบ Apidog กับ Jenkins

ดาวน์โหลด Apidog ฟรีเพื่อสร้าง test scenario แรกของคุณ จากนั้นเชื่อมต่อเข้ากับ Harness ด้วย YAML ด้านบน

Checklist ก่อนรัน Pipeline

ก่อนกด Run ให้ตรวจสอบรายการนี้:

สร้าง Harness secret แล้ว และ identifier ตรงกับ YAML
ใช้ single quote รอบ <+secrets.getValue("apidog_token")>
ใส่ test scenario ID ด้วย -t
ใส่ environment ID ด้วย -e
ใส่ junit ใน -r cli,junit
reports.spec.paths ชี้ไปที่ apidog-reports/*.xml
ถ้าใช้ Harness Cloud ให้ใช้ platform + runtime
ถ้าใช้ delegate ให้ใช้ infrastructure และระบุ image
ถ้าใช้ data file ให้เปิด cloneCodebase: true หรือเตรียมไฟล์ก่อนรัน CLI

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

Harness CI/CD คืออะไร?

Harness CI/CD เป็นแพลตฟอร์ม pipeline สำหรับ build, test และ deployment ซอฟต์แวร์ คุณกำหนด pipeline เป็น YAML ที่ประกอบด้วย stage และ step โดย CI stage จะรันบน Harness Cloud หรือ self-hosted delegate ส่วน CD stage ใช้จัดการ deployment

Harness CI ทำงานอย่างไร?

Pipeline มีรายการ stage แต่ละ CI stage มี spec สำหรับประกาศ build infrastructure และ execution block ส่วน execution block มี steps ตามลำดับ Run step ใช้รัน shell command เช่น ติดตั้งและรัน Apidog CLI

คุณจัดเก็บและใช้ Secrets ใน Harness อย่างไร?

สร้าง Text secret ใน Harness secret manager แล้วอ้างอิงใน YAML ด้วย:

<+secrets.getValue("identifier")>

ใช้ identifier ไม่ใช่ display name หาก secret อยู่ระดับ org หรือ account ให้ใช้ prefix org. หรือ account. และครอบ expression ด้วย single quote ใน shell command

คุณเผยแพร่ผลการทดสอบใน Harness อย่างไร?

เพิ่ม reports ใน Run step:

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml

จากนั้นรัน Apidog CLI พร้อม -r junit หรือ -r cli,junit เพื่อให้ CLI สร้าง JUnit XML ให้ Harness อ่าน

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

Harness มี Free Tier สำหรับ CI และการรันบน Harness Cloud ใช้ build credits ที่รวมอยู่ในแผนของคุณ รายละเอียดราคาและเครดิตอาจเปลี่ยนแปลงได้ ควรตรวจสอบหน้า pricing ปัจจุบันของ Harness ก่อนเลือก tier

ฉันสามารถรัน Apidog CLI โดยไม่ต้อง clone repository ได้หรือไม่?

ได้ ตั้งค่า cloneCodebase: false เมื่อ test scenario และ environment อยู่ใน Apidog Cloud CLI จะยืนยันตัวตนด้วย access token และดึง scenario/environment ตาม ID โดยไม่ต้องใช้ source code จาก repository ของคุณ

DEV Community

วิธีรัน Apidog CLI API Tests ใน Harness CI/CD

Harness CI/CD คืออะไร?

โครงสร้าง Run step สำหรับ Apidog CLI

Apidog CLI ในหนึ่งนาที

เก็บ Apidog access token เป็น Harness secret

Pipeline สำหรับ Harness Cloud

เผยแพร่ผลการทดสอบใน Harness

Pipeline สำหรับ self-hosted delegate

เลือกระหว่าง Harness Cloud กับ self-hosted delegate

การรันแบบ data-driven

ทำไมต้องออกแบบ test scenario ใน Apidog ก่อน

Checklist ก่อนรัน Pipeline

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

Harness CI/CD คืออะไร?

Harness CI ทำงานอย่างไร?

คุณจัดเก็บและใช้ Secrets ใน Harness อย่างไร?

คุณเผยแพร่ผลการทดสอบใน Harness อย่างไร?

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

ฉันสามารถรัน Apidog CLI โดยไม่ต้อง clone repository ได้หรือไม่?

Top comments (0)