วิธีการย้ายจาก Hoppscotch CLI ไปยัง Apidog CLI

Hoppscotch CLI เป็นวิธีที่สะอาดและฟรีในการเรียกใช้ชุด API ในเทอร์มินัลหรือ CI pipeline คำสั่ง hopp test จะอ่านไฟล์คอลเลกชัน ดำเนินการร้องขอแต่ละรายการ รันสคริปต์ pre-request และ test ของคุณ และจะออกจากระบบด้วยค่าที่ไม่ใช่ศูนย์เมื่อการยืนยันล้มเหลว สำหรับทีมจำนวนมาก แค่นั้นก็เพียงพอแล้ว

แต่ runner เป็นเพียงส่วนหนึ่งของงาน API เท่านั้น ในบางจุด คุณจะต้องจัดการกับเครื่องมือออกแบบแยกต่างหาก, mock server, เว็บไซต์เอกสาร และ runner โดยที่ไม่มีเครื่องมือใดใช้แหล่งความจริงเดียวกัน นั่นคือเมื่อทีมส่วนใหญ่เริ่มพิจารณาวิธีการย้ายจาก Hoppscotch CLI ไปยัง Apidog CLI Apidog รวมการออกแบบ, การดีบัก, การจำลอง, เอกสารประกอบ และการทดสอบเข้าไว้ในแพลตฟอร์มเดียว และ CLI ของมันรันการทดสอบใน CI โดยที่ runner ยังคงรูปแบบที่คุณคุ้นเคย สิ่งที่เปลี่ยนไปคือทุกสิ่งที่อยู่รอบๆ ตัวมัน

button

เมื่อคุณควร (และไม่ควร) ย้าย

ซื่อสัตย์กับตัวเองก่อน ถ้าความต้องการของคุณมีเพียงแค่ "รันคอลเลกชันใน CI ฟรี หากต้องการก็โฮสต์เองได้" Hoppscotch CLI ก็เป็นเครื่องมือที่ดีจริงๆ มันเป็นโอเพนซอร์ส runner ทำงานเร็ว และ @hoppscotch/cli มาในรูปแบบ npm package ปกติ ไม่ต้องอายที่จะอยู่กับมันต่อไป

ควรย้ายเมื่อมีสิ่งใดสิ่งหนึ่งต่อไปนี้เริ่มสร้างปัญหา:

คุณออกแบบ API ในเครื่องมือหนึ่ง, สร้าง mock ในอีกเครื่องมือหนึ่ง และเขียนเอกสารในเครื่องมือที่สาม และการทำให้ทุกอย่างซิงค์กันเป็นงานที่ต้องทำด้วยตนเอง
คุณต้องการให้การทดสอบ, mock server และเอกสารที่เผยแพร่ใช้คำจำกัดความโปรเจกต์เดียวกัน
คุณต้องการรายงานที่หลากหลายขึ้น (รายงาน HTML สำหรับผู้มีส่วนได้ส่วนเสีย, JSON สำหรับเครื่อง) พร้อมกับประวัติการรันที่โฮสต์บนคลาวด์
คุณต้องการจัดการ endpoints, schemas, environments และ branches เป็นโค้ดที่ CLI สามารถจัดการได้ ไม่ใช่แค่เรียกใช้งาน

หากรายการดังกล่าวฟังดูเหมือนกับสัปดาห์ทำงานของคุณ แพลตฟอร์มคือเหตุผลที่ต้องย้าย ไม่ใช่ runner นี่คือวิธีการทำอย่างสะอาด

ขั้นตอนที่ 1: ส่งออก Hoppscotch collection และ environment ของคุณ

ทุกอย่างใน Hoppscotch เป็น JSON ซึ่งทำให้การส่งออกเป็นไปอย่างง่ายดาย

จากแอป Hoppscotch (เว็บหรือเดสก์ท็อป) เปิดคอลเลกชันที่คุณรันใน CI ใช้เมนูของคอลเลกชันและเลือก Export ซึ่งจะให้ไฟล์ .json แก่คุณ ทำเช่นเดียวกันสำหรับ environment ที่คุณส่งด้วย -e: เปิดแผง environments และส่งออกไปยังไฟล์ JSON ของตัวเอง

หากคุณรัน CLI กับไฟล์ในเครื่องอยู่แล้ว คุณก็มีไฟล์เหล่านี้อยู่บนดิสก์แล้ว ขั้นตอน Hoppscotch CI โดยทั่วไปจะมีลักษณะดังนี้:

npm i -g @hoppscotch/cli
hopp test ./collections/checkout-api.json -e ./environments/staging.json

เก็บไฟล์ทั้งสองไว้ checkout-api.json คือคอลเลกชันของคุณ staging.json คือ environment ของคุณ สองไฟล์นี้คือข้อมูลทั้งหมดที่คุณจะย้ายไป

ข้อควรทราบเกี่ยวกับ Node versions ในตอนนี้ Hoppscotch CLI ปัจจุบันต้องการ Node.js v22 หรือใหม่กว่า; ทีมที่ใช้ Node 20 จะใช้ CLI v0.26.0 Apidog CLI ไม่ได้ผูกมัดคุณไว้กับสิ่งนั้น ดังนั้นการย้ายระบบจึงเป็นโอกาสที่จะละทิ้งข้อจำกัดเวอร์ชันด้วย

ขั้นตอนที่ 2: นำเข้าคอลเลกชันเข้าสู่ Apidog

สร้างโปรเจกต์ใน Apidog (หรือเปิดโปรเจกต์ที่มีอยู่) จากนั้นนำเข้าข้อมูลที่ส่งออกจาก Hoppscotch ของคุณ Apidog สามารถอ่านรูปแบบคอลเลกชันทั่วไปและ OpenAPI ได้ ดังนั้นคุณสามารถนำเข้าคอลเลกชันได้โดยตรง หาก API ของคุณมี OpenAPI spec ด้วย ให้นำเข้าส่วนนั้นด้วย Apidog จะตรวจสอบความถูกต้องของ spec เมื่อนำเข้า ดังนั้นปัญหาโครงสร้างจะปรากฏขึ้นทันทีแทนที่จะล้มเหลวเงียบๆ ระหว่างการรัน

แมป Hoppscotch environment ของคุณเข้ากับ Apidog environment โดยใช้ชื่อตัวแปรเดียวกัน หาก staging.json กำหนด base_url และ api_token ให้สร้างคีย์เหล่านั้นขึ้นมาใหม่ภายใต้ Apidog environment ที่ตรงกัน การใช้ชื่อเดียวกันหมายความว่าสคริปต์ทดสอบและ URL คำขอของคุณไม่จำเป็นต้องแก้ไข

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

ขั้นตอนที่ 3: แมป `hopp test` กับ `apidog run`

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

# Hoppscotch
hopp test ./collections/checkout-api.json -e ./environments/staging.json

# Apidog
apidog run --access-token $APIDOG_TOKEN -e "Staging"

ทั้งสองคำสั่งจะดำเนินการร้องขอทุกรายการตามลำดับ, รันสคริปต์ pre-request, รันการยืนยันการทดสอบของคุณ และคืนค่า exit code ที่ไม่เป็นศูนย์หากมีสิ่งใดล้มเหลว สัญญา exit-code นี้คือส่วนที่ CI ขึ้นอยู่กับ และมันถูกรักษาไว้ ดังนั้นตรรกะการผ่าน/ไม่ผ่านของ pipeline ของคุณจึงไม่เปลี่ยนแปลง

การรับรองความถูกต้องแตกต่างกันในวิธีที่เป็นประโยชน์ Hoppscotch ส่ง personal access token ด้วย --token สำหรับคอลเลกชันบนคลาวด์หรือแบบ self-hosted Apidog รับรองความถูกต้องด้วยการล็อกอินหรือ access token ซึ่งช่วยให้ CLI เข้าถึงทรัพยากรในโปรเจกต์ของคุณแทนที่จะเป็นไฟล์ที่ส่งออกเพียงไฟล์เดียว หากคุณเคยประสบปัญหาในการจัดการโทเค็นมาก่อน การแนะนำการรับรองความถูกต้อง จะแสดงตัวเลือกต่างๆ

ขั้นตอนที่ 4: แปลงการรันแบบขับเคลื่อนด้วยข้อมูล

เครื่องมือทั้งสองรองรับการทดสอบแบบขับเคลื่อนด้วยข้อมูล ดังนั้นการวนซ้ำข้อมูลจากไฟล์ CSV จึงยังคงทำงานได้หลังการย้าย

ใน Hoppscotch คุณจะส่งข้อมูลการวนซ้ำและจำนวน:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --iteration-count 50 \
  --iteration-data ./data/orders.csv

ใน Apidog, runner รับชุดข้อมูลด้วย -d มันรองรับ CSV และ JSON ดังนั้น orders.csv เดิมก็จะใช้งานได้หลังการนำเข้า:

apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -d ./data/orders.csv

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

ขั้นตอนที่ 5: แปลง reporters ของคุณ

การรายงานคือจุดที่แพลตฟอร์มเหนือกว่า และการแปลงก็ตรงไปตรงมา

Hoppscotch สร้างไฟล์ JUnit XML ด้วยแฟล็กเดียว ซึ่งระบบ CI ส่วนใหญ่จะแยกวิเคราะห์เพื่อใช้ในแผงทดสอบ:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --reporter-junit ./reports/results.xml

Apidog ให้คุณเลือก reporters ได้หลายแบบ: สรุป CLI ที่อ่านง่าย, รายงาน HTML ที่คุณสามารถมอบให้ผู้มีส่วนได้ส่วนเสีย และรายงาน JSON สำหรับเครื่องจักร คุณยังสามารถอัปโหลดผลลัพธ์ไปยังคลาวด์เพื่อดูประวัติการรันที่สามารถแชร์ได้

# Human-readable HTML report
apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report

หากแดชบอร์ด CI ของคุณคาดหวัง JUnit XML โดยเฉพาะ ให้พิจารณาการผนวกรวมนั้นในระหว่างการสลับ เนื่องจาก Apidog จะเน้นที่ reporters แบบ CLI/HTML/JSON และรายงานบนคลาวด์มากกว่าแฟล็ก JUnit สำหรับทีมส่วนใหญ่ รายงาน HTML พร้อมประวัติบนคลาวด์ที่อัปโหลดจะดีกว่าไฟล์ XML ดิบที่ไม่มีใครเปิดอ่าน คู่มือรายงานการทดสอบ จะอธิบายแต่ละรูปแบบและเวลาที่ควรใช้

ก่อนและหลัง: การแมปคำสั่ง

งาน	Hoppscotch CLI	Apidog CLI
ติดตั้ง	`npm i -g @hoppscotch/cli`	ตาม คู่มือการติดตั้ง
รัน collection	`hopp test collection.json`	`apidog run`
เลือก environment	`-e env.json`	`-e "Staging"`
โทเค็นการยืนยันตัวตน	`--token <pat>`	ล็อกอิน / `--access-token`
เป้าหมายแบบ Self-hosted / cloud	`--server <url>`	โปรเจกต์ + access token
อินพุตแบบขับเคลื่อนด้วยข้อมูล	`--iteration-data orders.csv`	`-d orders.csv`
รันซ้ำ	`--iteration-count 50`	ชุดข้อมูลสำหรับ iteration
เพิ่มดีเลย์ระหว่างคำขอ	`-d <ms>`	การตั้งค่าต่อ scenario
รายงาน JUnit	`--reporter-junit results.xml`	`-r json` (หรือ CLI / HTML)
ประวัติการรันบนคลาวด์	ไม่ได้สร้างมาให้	`--upload-report`

โปรดสังเกตแฟล็ก -d ในตารางนั้น ใน Hoppscotch -d คือดีเลย์เป็นมิลลิวินาที; ใน Apidog -d คือชุดข้อมูลสำหรับการรันแบบขับเคลื่อนด้วยข้อมูล ตัวอักษรเดียวกัน แต่งานต่างกัน นี่คือจุดที่คนมักจะพลาดเมื่อเปลี่ยนจาก hopp ไป apidog

ขั้นตอนที่ 6: เชื่อมต่อเข้ากับ GitHub Actions

ขั้นตอนสุดท้าย และเป้าหมายคือให้ build เป็นสีเขียวตลอดกระบวนการ เริ่มต้นด้วยการตั้งค่า Apidog job ควบคู่ไปกับ Hoppscotch ตัวเก่าก่อน ยืนยันว่าผ่าน จากนั้นจึงลบขั้นตอนเก่าทิ้ง อย่าเปลี่ยนโดยไม่ตรวจสอบให้ดี

name: API tests
on: [push, pull_request]

jobs:
  apidog-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API tests
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          apidog run \
            --access-token "$APIDOG_TOKEN" \
            -e "Staging" \
            -d ./data/orders.csv \
            -r html \
            --upload-report

เก็บ access token ของคุณเป็น repository secret ห้ามเก็บไว้ใน YAML เพราะ CLI จะคืนค่า exit code ที่ไม่เป็นศูนย์หากมีการยืนยันใดล้มเหลว ทำให้ job ล้มเหลวเมื่อการทดสอบของคุณล้มเหลว ซึ่งเป็นพฤติกรรมที่ทีมของคุณไว้วางใจจาก Hoppscotch อยู่แล้ว คู่มือ GitHub Actions ครอบคลุมการแคชและการรันแบบ matrix และ คู่มือ CI/CD pipeline ที่กว้างขึ้นจะจัดการกับ GitLab, Jenkins และอื่นๆ

เมื่อ Apidog job เป็นสีเขียวในการรันสองสามครั้ง ให้ลบขั้นตอน Hoppscotch และการติดตั้ง npm ออก การย้ายระบบเสร็จสิ้น build ไม่เคยเป็นสีแดง

คำพูดที่เป็นธรรมเกี่ยวกับ Hoppscotch

ทั้งหมดนี้ไม่ได้เป็นการวิจารณ์ Hoppscotch CLI runner ของมันทำงานเร็วและฟรี โปรเจกต์เป็นโอเพนซอร์สเต็มรูปแบบ และคุณสามารถโฮสต์ stack ทั้งหมดได้ด้วยตนเอง หากคุณต้องการ runner ที่เบาและไม่มีอะไรมากไปกว่านั้น มันก็ทำหน้าที่ของมันได้อย่างดี เหตุผลในการเปลี่ยนคือขอบเขตของงาน: เมื่อการออกแบบ, mock, เอกสาร และการทดสอบทั้งหมดจำเป็นต้องใช้คำจำกัดความเดียว runner แบบเดี่ยวไม่สามารถให้สิ่งนั้นได้ และแพลตฟอร์มแบบรวมศูนย์สามารถทำได้ เปรียบเทียบ runner ทั้งสองโดยตรงใน Apidog CLI vs Hoppscotch CLI และหากคุณกำลังพิจารณาแอปพลิเคชันมากกว่า CLI Postman vs Hoppscotch และ สรุปทางเลือกของ Hoppscotch จะให้ข้อมูลเพิ่มเติม