การทดสอบ API ส่วนใหญ่เริ่มต้นชีวิตใน GUI คุณคลิกไปมา เพิ่ม assertions สองสามตัว และรันด้วยตนเอง นั่นใช้ได้จนกว่าคุณจะต้องใช้การทดสอบเดียวกันนี้เพื่อรันทุกครั้งที่พุช ทุกคืน หรือภายในไปป์ไลน์ที่ไม่มีใครเฝ้าดู ณ จุดนั้น คุณต้องการคำสั่งเดียวที่คุณสามารถพิมพ์, เขียนสคริปต์ และส่งต่อไปยัง CI ได้
คำสั่งนั้นคือ Apidog CLI บทช่วยสอนนี้จะแนะนำคุณตลอดการทดสอบ REST API จริงแบบครบวงจรจากเทอร์มินัลของคุณ: ติดตั้งเครื่องมือ, นำเข้า API, ตั้งค่าสภาพแวดล้อม, สร้างสถานการณ์การทดสอบ, รันด้วย assertions, ป้อนข้อมูล และรวบรวมรายงาน ทุกคำสั่งและเอาต์พุตด้านล่างมาจากการรันจริงบน Apidog CLI เวอร์ชัน 2.2.2 กับ API สาธารณะที่ใช้งานจริง ดังนั้นคุณสามารถทำตามและได้ผลลัพธ์เดียวกัน
หากคุณต้องการด้านภาพของแพลตฟอร์มเดียวกัน คุณสามารถ ดาวน์โหลด Apidog และออกแบบการทดสอบในแอปก่อนได้ แต่ทุกอย่างที่นี่จะยังคงอยู่บน Command Line
สิ่งที่คุณจะสร้าง
คุณจะทดสอบ restful-api.dev ซึ่งเป็น REST API สาธารณะฟรีที่มีการดำเนินการ CRUD จริงบนทรัพยากร /objects เมื่อสิ้นสุด คุณจะได้:
- โปรเจกต์ Apidog ที่สร้างจากไฟล์ OpenAPI
- สถานการณ์การทดสอบสามขั้นตอนที่สร้างอ็อบเจกต์, อ่านกลับ และลบ โดยมีการยืนยันในแต่ละขั้นตอน
- การรันที่ขับเคลื่อนด้วยข้อมูลที่ทำซ้ำคำขอหนึ่งครั้งต่อแถวข้อมูลทดสอบ
- รายงาน CLI, HTML, JSON และ JUnit รวมถึงรายงานบนคลาวด์ที่แชร์ได้
ขั้นตอนเดียวกันนี้สามารถปรับขนาดไปใช้กับ API ของคุณเองได้ และเป็นรากฐานสำหรับการรัน การทดสอบ API ใน CI/CD
ก่อนเริ่มต้น
คุณต้องมี Node.js 16 หรือใหม่กว่า และบัญชี Apidog หากคุณกำลังเปรียบเทียบรันเนอร์ก่อนเวอร์ชันสั้นๆ คือ Apidog CLI รันสถานการณ์การทดสอบเต็มรูปแบบและจัดการทรัพยากร API เป็นโค้ด ซึ่งทำให้แตกต่างจาก Newman และ Postman CLI
ขั้นตอนที่ 1: ติดตั้งและเข้าสู่ระบบ
ติดตั้ง CLI ทั่วโลกจาก npm:
npm install -g apidog-cli@latest
ยืนยันว่าติดตั้งแล้ว:
apidog --version
# 2.2.2
ตอนนี้ยืนยันตัวตน รับโทเค็นจากแอป Apidog ใต้รูปโปรไฟล์ของคุณ, การตั้งค่าบัญชี, โทเค็นการเข้าถึง API จากนั้นรัน:
apidog login --with-token <YOUR_TOKEN>
โทเค็นจะถูกบันทึกไว้ที่ ~/.apidog/config.toml ดังนั้นคุณทำสิ่งนี้เพียงครั้งเดียวต่อเครื่อง ตรวจสอบว่าคุณเป็นใคร:
ทุกคำสั่งจะส่งคืน JSON ที่มีโครงสร้างพร้อมแฟล็ก success และ agentHints ที่เป็นประโยชน์ ซึ่งทำให้เอาต์พุตง่ายต่อการเขียนสคริปต์หรือส่งไปยัง jq
ขั้นตอนที่ 2: สร้างโปรเจกต์
เลือกทีมที่จะสร้างโปรเจกต์ จากนั้นสร้างโปรเจกต์:
apidog team list
apidog project create --team 329562 --name "CLI Field Test"
คุณจะได้รับ id โปรเจกต์ใหม่กลับมา
บันทึกไว้ในตัวแปร shell เพื่อให้บทช่วยสอนที่เหลือสามารถคัดลอกและวางได้:
PID=1314366 # แทนที่ด้วย id โปรเจกต์ของคุณ
apidog project get $PID
ขั้นตอนที่ 3: นำเข้า REST API ของคุณ
คุณสามารถสร้าง endpoints ด้วยตนเองได้ แต่การนำเข้าไฟล์ OpenAPI นั้นเร็วกว่าและสะท้อนถึงวิธีที่โปรเจกต์จริงเริ่มต้น นี่คือสเปกเล็กๆ ที่อธิบาย endpoints CRUD ของ /objects (บันทึกเป็น objects-api.openapi.json):
{
"openapi": "3.0.3",
"info": { "title": "Objects API", "version": "1.0.0" },
"servers": [{ "url": "https://api.restful-api.dev" }],
"paths": {
"/objects": {
"get": { "summary": "List objects" },
"post": { "summary": "Create object" }
},
"/objects/{id}": {
"get": { "summary": "Get object by id" },
"put": { "summary": "Update object" },
"delete": { "summary": "Delete object" }
}
}
}
นำเข้า:
apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5 (สร้าง 5 endpoints, 0 ข้อผิดพลาด)
ผู้นำเข้ายังอ่าน openapi, postman, har, insomnia, jmeter และอื่นๆ แสดงรายการที่เข้ามา:
apidog endpoint list --project $PID
# 37921721 get /objects
# 37921722 post /objects
# 37921723 get /objects/{id}
# 37921724 put /objects/{id}
# 37921725 delete /objects/{id}
ขั้นตอนที่ 4: ตั้งค่าสภาพแวดล้อม
สภาพแวดล้อมจะเก็บ URL พื้นฐานและตัวแปรใดๆ ที่การทดสอบของคุณนำกลับมาใช้ใหม่ สร้างหนึ่งและบันทึก id ของมัน:
apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917 # แทนที่ด้วย id สภาพแวดล้อมของคุณ
คุณจะส่ง -e $ENV ไปยังคำสั่งรันในภายหลังเพื่อให้การทดสอบรู้ว่าจะส่งคำขอไปที่ใด
ขั้นตอนที่ 5: ผ่านประตูการเขียนระบบอัตโนมัติ
นี่คือสิ่งแรกที่ทำให้คนสับสน สถานการณ์การทดสอบและข้อมูลการทดสอบเป็นทรัพยากรระบบอัตโนมัติ และการเขียนไปยัง main branch ของคุณจากเครื่องมือภายนอกจะถูกบล็อกโดยค่าเริ่มต้น:
apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "ต้องระบุ Automation caller branch" }
นี่คือตัวป้องกัน ไม่ใช่ข้อผิดพลาด คุณมีสองวิธีในการผ่านไปได้:
- เปิดใช้งานการอนุญาตแก้ไขโดยตรงในแอป Apidog บนเดสก์ท็อปภายใต้ Project Settings, Feature Settings, AI Feature Settings, External AI Edit Permissions
- ทำงานบน AI branch ซึ่งช่วยให้การเปลี่ยนแปลงระบบอัตโนมัติแยกออกจากกันจนกว่าคุณจะเลือกที่จะรวมเข้าด้วยกัน เส้นทางนี้จะยังคงอยู่บน command line อย่างสมบูรณ์ ดังนั้นเราจะใช้สิ่งนี้
สร้าง branch จาก main:
apidog branch create --project $PID --type ai \
--name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"
รูปแบบการตั้งชื่อ ai/YYYYMMDD-from-<source>-<feature> เป็นไปตามข้อกำหนดของ CLI โปรดทราบว่า import, environment create และการแก้ไข endpoint ไม่ได้ถูกจำกัด เฉพาะทรัพยากรระบบอัตโนมัติเท่านั้นที่ถูกจำกัด
ขั้นตอนที่ 6: สร้างสถานการณ์การทดสอบ
สถานการณ์คือลำดับการไหลของคำขอพร้อม assertions ระหว่างกัน คุณสร้างโครงสร้างหลักก่อน จากนั้นจึงเพิ่มขั้นตอน สร้างบน AI branch ของคุณ:
apidog test-scenario create --project $PID --branch "$BR" \
--name "Object CRUD lifecycle" \
--description "สร้าง, อ่าน, แล้วลบออบเจกต์และยืนยันในแต่ละขั้นตอน" \
--folder-id 0 --priority 1
SID=1836498 # id ของสถานการณ์ที่ส่งคืน
ขั้นตอนถูกเพิ่มผ่าน update ด้วยไฟล์ JSON กฎทองของการเขียน JSON คือการตรวจสอบก่อนที่คุณจะส่ง เพื่อที่คุณจะไม่ได้ผลักดัน payload ที่ผิดรูปแบบ:
apidog cli-schema get test-scenario-update # ดูรูปร่างที่แน่นอน
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "ไฟล์ข้อมูลถูกต้อง"
แต่ละขั้นตอนคือคำขอรวมถึงสคริปต์เล็กๆ ที่ยืนยันการตอบสนองและส่งข้อมูลไปยังขั้นตอนถัดไป นี่คือรูปร่างของขั้นตอนการสร้าง ซึ่งโพสต์ออบเจกต์ใหม่และบันทึก id ของมันไว้สำหรับขั้นตอนถัดไป:
{
"type": "customHttp",
"name": "Create object",
"customHttpRequest": {
"path": "https://api.restful-api.dev/objects",
"method": "post",
"requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Field Test\",\"data\":{\"price\":42}}" },
"postProcessors": [{
"type": "customScript",
"data": "pm.test('create returns 200', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
"enable": true
}],
"projectId": 1314366
}
}
ขั้นตอนถัดไปจะใช้ {{objId}} ซ้ำใน URL เพื่อดึงและลบออบเจกต์เดียวกัน ใช้ไฟล์สามขั้นตอนทั้งหมด:
apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "สำเร็จ": true
คุณไม่จำเป็นต้องสร้างสถานการณ์เป็น JSON การสร้างด้วยภาพใน Apidog และการรันจาก CLI นั้นถูกต้องพอๆ กัน เส้นทาง JSON มีความสำคัญเมื่อคุณต้องการให้การทดสอบของคุณมีการควบคุมเวอร์ชันและได้รับการตรวจสอบเหมือนโค้ดอื่นๆ
ขั้นตอนที่ 7: รันจาก Command Line
นี่คือผลลัพธ์ รันสถานการณ์ด้วย CLI reporter:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli
❏ Object CRUD lifecycle
↳ Create object POST .../objects [200 OK]
✓ create returns 200 ✓ response has an id ✓ name was echoed back
↳ Get the created object GET .../objects/ff80...3de [200 OK]
✓ get returns 200 ✓ id matches the created object ✓ price persisted in data
↳ Delete the object DELETE .../objects/ff80...3de [200 OK]
✓ delete returns 200
Http Requests 3 / 0 failed
Assertions 7 / 0 failed
สามคำขอ, เจ็ด assertions, ศูนย์ข้อผิดพลาด และ id ที่สร้างขึ้นไหลจากขั้นตอนแรกไปยังสองขั้นตอนถัดไป นั่นคือการทดสอบ API ที่สมบูรณ์แบบที่รันโดยไม่ต้องคลิกเลยแม้แต่ครั้งเดียว
ต้องการไฟล์แทนเอาต์พุตคอนโซลหรือไม่? ขอรายงานหลายรายการพร้อมกันและชี้ไปยังโฟลเดอร์:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
-r cli,html,json,junit --out-dir ./reports --out-file "crud-report"
ls ./reports
# crud-report.html crud-report.json crud-report.xml
JUnit XML คือสิ่งที่ CI server ของคุณอ่านเพื่อแสดงผลการผ่าน/ไม่ผ่านในแต่ละบิลด์ รายงาน HTML คือรายงานที่คุณแชร์กับเพื่อนร่วมทีม
ขั้นตอนที่ 8: รันการทดสอบเดียวกันกับอินพุตหลายรายการ
ชุดการทดสอบจริงครอบคลุมมากกว่าหนึ่งกรณี การรันที่ขับเคลื่อนด้วยข้อมูลจะทำซ้ำสถานการณ์หนึ่งครั้งต่อแถวข้อมูล ดังนั้นคุณจึงทดสอบอินพุตสิบรายการโดยไม่ต้องเขียนสิบสถานการณ์ นี่เป็นแนวคิดเดียวกับการ ทดสอบ API แบบพารามิเตอร์จาก CSV และ JSON
ใส่แถวของคุณในไฟล์:
[
{ "name": "Pixel 8 Pro", "price": 999 },
{ "name": "iPhone 15", "price": 899 },
{ "name": "Galaxy S24", "price": 799 }
]
อ้างอิงข้อมูลด้วย -d และปล่อยให้สถานการณ์อ่าน {{name}} และ {{price}} จากแต่ละแถว:
apidog run -t $DID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli
Iteration 1/3 … ✓ แถวถูกสร้าง (200) ✓ ชื่อตรงกับแถวข้อมูล
Iteration 2/3 … ✓ แถวถูกสร้าง (200) ✓ ชื่อตรงกับแถวข้อมูล
Iteration 3/3 … ✓ แถวถูกสร้าง (200) ✓ ชื่อตรงกับแถวข้อมูล
Iterations 3 / 0 ไม่สำเร็จ Assertions 6 / 0 ไม่สำเร็จ
สามแถวเข้า สามการวนซ้ำออก เปลี่ยนไฟล์เป็น CSV และไม่มีอะไรเปลี่ยนแปลง
ขั้นตอนที่ 9: รวบรวมรายงาน
การรันในเครื่องจะสร้างไฟล์ หากต้องการรับรายงานที่ทั้งทีมของคุณสามารถเปิดในเบราว์เซอร์ได้ ให้เพิ่ม --upload-report:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# ข้อมูลที่รันโดย Apidog CLI อัปโหลดไปยังคลาวด์สำเร็จแล้ว
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398
ข้อควรทราบอย่างหนึ่ง: รายงานบนคลาวด์จะถูกติดแท็กด้วย branch ที่รันอยู่ เนื่องจากรันนี้เกิดขึ้นบน AI branch ของคุณ คำสั่ง apidog test-report list --project $PID (ซึ่งกำหนดเป้าหมาย main) จะไม่แสดงรายงานนี้ คุณสามารถดึงข้อมูลได้โดยใช้ id จากลิงก์อัปโหลดแทน:
apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json
ขั้นตอนที่ 10: ส่งออก API ของคุณเป็นเอกสารหรือสเปก
CLI ยังสามารถส่งออกข้อมูลได้ ส่งออกโปรเจกต์เป็นไฟล์ OpenAPI, Markdown หรือเอกสาร HTML:
apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html
สิ่งนี้มีประโยชน์สำหรับการคอมมิตสเปกใหม่ในการเปลี่ยนแปลงทุกครั้ง หรือการเผยแพร่เอกสารแบบคงที่จากไปป์ไลน์
ขั้นตอนที่ 11: เชื่อมต่อเข้ากับ CI/CD
ทุกสิ่งที่คุณรันด้วยตนเองจะกลายเป็นสามบรรทัดในไปป์ไลน์ แกนหลักคือการติดตั้ง จากนั้นรันด้วย JUnit reporter เพื่อให้ CI server สามารถอ่านผลลัพธ์ได้:
- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports
จัดเก็บโทเค็นเป็นความลับ และทำให้บิลด์ล้มเหลวเมื่อการทดสอบล้มเหลว (CLI จะคืนค่า exit code ที่ไม่ใช่ศูนย์เมื่อเกิดความล้มเหลว) สำหรับเวิร์กโฟลว์ที่สมบูรณ์แบบที่สามารถคัดลอกและวางได้ โปรดดูคู่มือการรัน การทดสอบ Apidog CLI ใน GitHub Actions หรือเรียกดู เครื่องมือทดสอบ API อัตโนมัติที่เหมาะกับไปป์ไลน์
สรุป
คุณเปลี่ยนจากเทอร์มินัลว่างเปล่าไปเป็นการทดสอบ API ที่ขับเคลื่อนด้วยข้อมูลที่ผ่าน พร้อมรายงานที่แชร์ได้ และคุณไม่เคยออกจาก command line เลย รูปแบบจะเหมือนกันเสมอ: นำเข้าหรือออกแบบ API ของคุณ, สร้างสภาพแวดล้อม, สร้างสถานการณ์พร้อม assertions จากนั้นรันด้วย apidog run เมื่อคำสั่งนั้นทำงานได้ในเครื่องแล้ว การนำไปใช้ใน CI ก็เป็นการเปลี่ยนแปลงเพียงสามบรรทัด
ชี้ขั้นตอนเดียวกันนี้ไปที่ API ของคุณเอง คอมมิตไฟล์สถานการณ์พร้อมกับโค้ดของคุณ และการทดสอบของคุณจะทำงานได้ทุกที่ที่มี shell ดาวน์โหลด Apidog เพื่อเริ่มต้น และเก็บ ทางเลือกสำหรับ curl สำหรับการทดสอบ REST API ไว้สำหรับตรวจสอบแบบครั้งเดียวที่ CLI อาจจะเกินความจำเป็น