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

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

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

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

คุณกำหนดทุกอย่างเป็น YAML ไปป์ไลน์หนึ่งๆ ประกอบด้วย Stage หนึ่งหรือหลาย Stage แต่ละ Stage มีประเภท และ CI Stage จะทำงานบนโครงสร้างพื้นฐานการสร้าง ภายใน Stage บล็อกการ Execute จะเก็บรายการ Steps ที่จัดลำดับไว้ ซึ่งจะรันคำสั่งของคุณ

โมเดลนี้สามารถนำไปใช้กับการทดสอบ API ได้อย่างลงตัว คุณเพิ่ม CI Stage, ใส่ Step ที่รันคำสั่งทดสอบของคุณ และให้ Harness ตรวจสอบการสร้างจากผลลัพธ์ หากการทดสอบล้มเหลว Step นั้นก็จะล้มเหลว และไปป์ไลน์จะหยุดทำงาน

Harness อ่าน JUnit XML สำหรับการรายงานผลการทดสอบ เนื่องจาก Apidog CLI สามารถสร้าง JUnit ได้ คุณจะได้รับแท็บ Tests ดั้งเดิมที่แสดงจำนวนการผ่านและล้มเหลวในการสร้างทุกครั้ง ไม่จำเป็นต้องมีโค้ดเชื่อมต่อ

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

ลำดับชั้นของ YAML มีความเข้มงวด ดังนั้นการทำความเข้าใจโครงสร้างที่ซ้อนกันก่อนจะช่วยได้ ไปป์ไลน์ CI มีโครงสร้างดังนี้จากบนลงล่าง:

• pipeline เก็บเมตาดาต้าและรายการ stages
• แต่ละ stage มี type: CI และ spec
• spec ของ stage จะประกาศโครงสร้างพื้นฐานการสร้างและบล็อก execution
• execution เก็บรายการ steps
• แต่ละ step มี type, name, identifier และ spec ของตัวเอง

สำหรับการรันคำสั่งเชลล์ ประเภทของ step คือ Run spec ของ Run step มีฟิลด์ shell (Bash, Sh, PowerShell, Pwsh หรือ Python) และฟิลด์ command ที่เก็บสคริปต์ของคุณ คุณสามารถเขียนคำสั่งหลายบรรทัดได้ด้วย YAML block scalar |-

Run step เดียวนี้เป็นสิ่งที่คุณต้องการทั้งหมดในการติดตั้งและรัน Apidog CLI ทุกสิ่งในคู่มือนี้คือการกำหนดค่ารอบๆ step เดียวนั้น

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

Apidog CLI เป็นตัวรันบรรทัดคำสั่งสำหรับสถานการณ์การทดสอบที่คุณสร้างขึ้นด้วยภาพใน Apidog คุณออกแบบการทดสอบในแอป จากนั้นรันแบบ Headless ในไปป์ไลน์ใดก็ได้ คล้ายกับที่ Newman รัน Postman collections หากคุณต้องการเปรียบเทียบดู Apidog CLI กับ Newman

คุณติดตั้งจาก npm และรันคำสั่งเดียว:

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

มีบางแฟล็กที่สำคัญสำหรับ CI แฟล็ก --access-token ใช้สำหรับการยืนยันตัวตนการรันบนคลาวด์และไม่มีรูปแบบย่อ แฟล็ก -e กำหนดสภาพแวดล้อมและจำเป็นต้องใช้ แฟล็ก -t เลือกสถานการณ์การทดสอบด้วย ID แฟล็ก -r เลือกผู้รายงานผล และ junit เป็นหนึ่งในค่าที่รองรับ (cli, html, json, junit) แฟล็ก --out-dir ควบคุมตำแหน่งที่รายงานจะถูกบันทึก ซึ่งค่าเริ่มต้นคือ ./apidog-reports

การเลือก -r cli,junit เป็นสะพานเชื่อมไปยัง Harness CLI จะเขียน JUnit XML ลงในไดเรกทอรีเอาต์พุต และ Harness จะอ่านโดยตรง สำหรับข้อมูลเพิ่มเติมเกี่ยวกับสิ่งที่ CLI สร้างขึ้น โปรดดูคู่มือ รายงานการทดสอบ Apidog CLI

การจัดเก็บ Apidog access token ของคุณเป็น Harness secret

อย่าฮาร์ดโค้ดโทเค็นใน YAML เด็ดขาด เพิ่มลงใน Harness secret manager ก่อน จากนั้นจึงอ้างอิง

ใน Harness UI ให้ไปที่การตั้งค่าโปรเจกต์ของคุณ (หรือ org/account), เปิด Secrets, และสร้าง Text secret ใหม่ ตั้งชื่อตัวระบุว่า apidog_token ตัวระบุคือสิ่งที่คุณอ้างอิงใน YAML และแตกต่างจากชื่อที่แสดง

คุณอ้างอิง secret ด้วยนิพจน์นี้:

<+secrets.getValue("apidog_token")>

ใช้ตัวระบุที่อยู่ภายในเครื่องหมายคำพูด ไม่ใช่ชื่อที่แสดง สำหรับ Secret ที่อยู่ในขอบเขตขององค์กร ให้เพิ่ม org. นำหน้า เช่น <+secrets.getValue("org.apidog_token")> สำหรับ Secret ที่อยู่ในขอบเขตของบัญชี ให้ใช้ account. แทน

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

ไปป์ไลน์ Harness Cloud (จุดเริ่มต้นที่แนะนำ)

Harness Cloud มอบเครื่องสร้างที่จัดการโดย Harness พร้อม Node.js และ npm ที่ติดตั้งไว้ล่วงหน้า ไม่ต้องดูแลโครงสร้างพื้นฐาน และ Linux ก็พร้อมใช้งานทันที นี่เป็นวิธีที่เร็วที่สุดในการทำให้ไปป์ไลน์ทำงานได้

บน Harness Cloud spec ของ stage จะใช้บล็อก platform และบล็อก runtime ที่มี type: Cloud คุณไม่ต้องระบุ image ใน Run step ที่นี่ เนื่องจากเครื่องที่จัดการมีเครื่องมืออยู่แล้ว

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

แทนที่ 605067 ด้วย ID ของสถานการณ์ทดสอบของคุณ และ 1629989 ด้วย ID ของสภาพแวดล้อมของคุณ แฟล็ก -n 1 จะรันหนึ่งรอบ ตั้งค่า cloneCodebase: false เนื่องจากการทดสอบอยู่ใน Apidog Cloud ดังนั้นไปป์ไลน์จึงไม่จำเป็นต้องใช้ repository ของคุณ

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

บล็อก reports บน Run step เป็นส่วนที่แสดงผลลัพธ์ใน Harness โดยจะใช้ type เป็น JUnit และ spec ที่มีรายการ paths ชี้ไปยังไฟล์ XML ของคุณ

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

Harness วิเคราะห์เฉพาะ JUnit XML สำหรับการรายงานแบบ Native หลังจากสร้างเสร็จ คุณจะเห็นแท็บ Tests ที่แสดงแต่ละสถานการณ์ สถานะ และเวลา Glob apidog-reports/*.xml จะจับคู่ไฟล์ที่ CLI เขียนด้วย -r cli,junit ลงในไดเรกทอรีเอาต์พุตเริ่มต้น

Harness ยังมี Test Intelligence ซึ่งใช้ประเภท Step Test แยกต่างหากเพื่อรันเฉพาะการทดสอบที่ได้รับผลกระทบจากการเปลี่ยนแปลงโค้ด การปรับปรุงนี้มุ่งเป้าไปที่การทดสอบหน่วยระดับภาษา ไม่ใช่สถานการณ์ API แบบ Headless สำหรับการนำเข้าเอาต์พุต Apidog CLI, Run step ธรรมดาพร้อมบล็อก reports ของ JUnit คือวิธีที่ถูกต้อง

หากคุณเปลี่ยนผู้รายงานผลเมื่อใดก็ตาม ให้เก็บ junit ไว้ในรายการ -r เป็นอย่างน้อย หากไม่มีไฟล์นี้ CLI จะไม่เขียน XML และแท็บ Tests จะยังคงว่างเปล่าแม้ว่า Step นั้นจะผ่านก็ตาม

ทางเลือก Delegate ที่โฮสต์ด้วยตนเอง

ใช้การสร้างที่สนับสนุนโดย Delegate เมื่อคุณต้องการเข้าถึงเครือข่ายส่วนตัว, รันไทม์ที่กำหนดเองหรือแบบเดิม, หรือคุณต้องการหลีกเลี่ยงเครดิตการสร้างของ Harness Cloud Kubernetes delegate จะรันแต่ละ Stage เป็น Pod

โครงสร้างจะเปลี่ยนไปสองทาง spec ของ stage จะใช้บล็อก infrastructure แทน platform และ runtime และบนโครงสร้างพื้นฐาน Kubernetes แต่ละ Run step จะต้องประกาศ connectorRef และ image เนื่องจาก step จะทำงานภายในคอนเทนเนอร์ที่คุณระบุ

        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

บรรทัด image: node:20 จะให้ Node.js และ npm ภายใน Pod ค่า connectorRef ชี้ไปยังตัวเชื่อมต่อ Kubernetes และ Docker ที่ลงทะเบียนไว้ของคุณ อย่าผสมผสานรูปแบบโครงสร้างพื้นฐานทั้งสองใน Stage เดียวกัน Stage จะเป็น Harness Cloud (platform บวก runtime) หรือ Delegate-backed (infrastructure) อย่างใดอย่างหนึ่งเท่านั้น ไม่ใช่ทั้งสองอย่าง

การเลือกระหว่าง Harness Cloud กับ Delegate

เลือกตามตำแหน่งที่ API ของคุณอยู่และผู้ที่เป็นเจ้าของเครื่อง Build

เริ่มต้นด้วย Harness Cloud หากสภาพแวดล้อม Apidog ของคุณเชื่อมต่อกับ Public Endpoint ย้ายไปใช้ Delegate เมื่อสภาพแวดล้อมการทดสอบของคุณอยู่เบื้องหลัง VPN หรือต้องการรันไทม์ที่คุณควบคุม Run step และคำสั่ง Apidog จะยังคงเหมือนกันเกือบทั้งหมดระหว่างทั้งสองแบบ

การรันที่ขับเคลื่อนด้วยข้อมูล

คุณสามารถป้อนไฟล์ CSV หรือ JSON เข้าไปในการรันสำหรับการทดสอบแบบ Parameterized แฟล็ก -d (ชื่อเต็ม --iteration-data) จะรับพาธของไฟล์ข้อมูล และ -n กำหนดจำนวนรอบ

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 Run step คุณจะต้อง git clone หรือเตรียมไฟล์ข้อมูลก่อน จากนั้นจึงชี้ -d ไปที่พาธของไฟล์ สำหรับรูปแบบฉบับเต็ม โปรดดู การทดสอบที่ขับเคลื่อนด้วยข้อมูลของ Apidog CLI และคู่มือ การทดสอบ API แบบอัตโนมัติ ที่ครอบคลุมมากขึ้น

ทำไมต้องออกแบบการทดสอบใน Apidog ก่อน

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

คุณออกแบบการทดสอบด้วย Visual Builder โดยไม่ต้องใช้ Scripting คุณสามารถเชื่อมโยงคำขอ, ดึงค่าจาก Response หนึ่งไปยังอีก Response หนึ่ง, และเพิ่ม Assertions ผ่าน UI ได้ จากนั้น CLI จะรันชุดการทดสอบที่แน่นอนนั้นแบบ Headless ใน Harness ดังนั้นสิ่งที่คุณดีบักในเครื่องก็คือสิ่งที่จะรันในไปป์ไลน์

เนื่องจาก Apidog เป็น OpenAPI-native พร้อมรองรับ Branch และ Team Workspace วิศวกร QA และนักพัฒนา Backend ของคุณจึงใช้แหล่งข้อมูลที่เป็นความจริงแหล่งเดียวกัน สถานการณ์ที่ได้รับการอนุมัติใน Branch จะกลายเป็นสถานการณ์เดียวกันกับที่คำสั่ง apidog run ของคุณรัน สำหรับรูปแบบไปป์ไลน์ที่กว้างขึ้น, คู่มือเบื้องต้น CI/CD คืออะไร และ คู่มือ GitHub Actions workflow จะครอบคลุม CLI เดียวกันในระบบอื่นๆ บทแนะนำ Jenkins ใน การผสานรวมการทดสอบ Apidog กับ Jenkins ใช้รูปแบบคำสั่งเดียวกัน

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

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

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

Harness CI/CD เป็นแพลตฟอร์มไปป์ไลน์สำหรับการสร้าง, ทดสอบ, และ Deployment ซอฟต์แวร์ คุณกำหนดไปป์ไลน์เป็น YAML ที่ประกอบด้วย Stage และ Step CI stage จะทำงานบนโครงสร้างพื้นฐานการสร้าง ไม่ว่าจะเป็นเครื่อง Cloud ที่จัดการโดย Harness หรือ Self-hosted Delegate และ CD stage จะจัดการการ Deployment

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

ไปป์ไลน์หนึ่งๆ มีรายการ Stage แต่ละ CI stage มี Spec ที่ประกาศโครงสร้างพื้นฐานการสร้างและบล็อก Execution บล็อก Execution จะรันรายการ Step ที่จัดลำดับไว้ Run step จะรันคำสั่งเชลล์ ซึ่งเป็นที่ที่คุณติดตั้งและรัน Apidog CLI

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

สร้าง Text secret ใน Harness secret manager และจดบันทึกตัวระบุของมัน อ้างอิงใน YAML ด้วย <+secrets.getValue("identifier")> โดยใช้ตัวระบุแทนชื่อที่แสดง ใส่ org. หรือ account. เป็นคำนำหน้าสำหรับขอบเขตเหล่านั้น และห่อหุ้มนิพจน์ด้วยเครื่องหมายคำพูดเดี่ยวภายในคำสั่งเชลล์

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

เพิ่มบล็อก reports ไปยัง Run step ของคุณด้วย type: JUnit และรายการ paths ที่ชี้ไปยังไฟล์ XML ของคุณ Harness จะวิเคราะห์ JUnit XML และแสดงผลลัพธ์บนแท็บ Tests ของ Build Apidog CLI จะสร้าง XML นี้เมื่อคุณส่ง -r junit หรือ -r cli,junit

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

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

ฉันสามารถรันการทดสอบ Apidog CLI โดยไม่ต้องโคลน Repo ของฉันได้หรือไม่?

ใช่ ตั้งค่า cloneCodebase: false บน Stage เมื่อการทดสอบของคุณอยู่ใน Apidog Cloud CLI จะยืนยันตัวตนด้วย Access Token ของคุณและดึงสถานการณ์และสภาพแวดล้อมด้วย ID ดังนั้นไปป์ไลน์จึงไม่จำเป็นต้องใช้ Source Code ของคุณสำหรับการรันการทดสอบ