วิธีใช้ Apidog CLI ใน Windsurf

Cascade ของ Windsurf ทำงานเป็นวงรอบ: แก้ไขไฟล์ รันคำสั่งเทอร์มินัล อ่านผลลัพธ์ แล้วตัดสินใจทำงานต่อไป แต่การทดสอบ API ที่อยู่หลัง GUI ของ Apidog จะไม่เข้ามาอยู่ในวงรอบนี้จนกว่าจะมีคนคลิกเอง วิธีเชื่อมทั้งสองส่วนคือใช้ Apidog CLI เพื่อให้ Cascade รันสถานการณ์ทดสอบ อ่าน exit code และแก้ไขโค้ดเมื่อผลลัพธ์ล้มเหลว

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

Apidog CLI คือแพ็กเกจ npm ชื่อ apidog-cli ที่ใช้รันสถานการณ์ทดสอบซึ่งสร้างไว้ใน Apidog ได้จากเทอร์มินัลโดยตรง เมื่อ CLI พร้อมใช้งานและ Cascade รู้คำสั่งที่ต้องรัน การทดสอบ API จะทำงานในวงรอบเดียวกับ unit test: รันคำสั่ง ตรวจสอบรหัสออก และใช้ผลลัพธ์เพื่อทำงานต่อ

ก่อนเริ่ม ให้ติดตั้งและยืนยันตัวตนของ CLI ให้เรียบร้อยตาม วิธีติดตั้ง Apidog CLI ด้วยเอเจนต์โค้ดดิ้ง AI บทความนี้สมมติว่าคำสั่งต่อไปนี้แสดงหมายเลขเวอร์ชันแล้ว:

apidog --version

เครื่องของคุณควรผ่านการยืนยันตัวตนแล้วด้วย apidog login

Windsurf ที่ใช้ในบทความนี้คืออะไร

Windsurf เป็น IDE แบบ agentic ของ Codeium โดยมีเอเจนต์ชื่อ Cascade ที่สามารถอ่าน repository แก้ไขไฟล์ และรัน shell command ในเทอร์มินัลภายใน IDE ได้ การรันคำสั่งอัตโนมัติจะขึ้นอยู่กับการตั้งค่าของคุณ

หากยังไม่ได้ตั้งค่า Windsurf ให้เริ่มจาก วิธีดาวน์โหลดและติดตั้ง Windsurf จากนั้นกำหนดกฎระดับโปรเจกต์เพื่อบอก Cascade ว่าต้องรัน Apidog CLI เมื่อใดและอย่างไร

ขั้นตอนที่ 1: เพิ่มกฎ Apidog ใน .windsurf/rules

Cascade อ่านกฎของโปรเจกต์จากไฟล์ Markdown ก่อนเริ่มทำงาน ให้สร้างไฟล์ใน .windsurf/rules/ ที่ root ของ repository โดยแยกหนึ่งกฎต่อหนึ่งไฟล์

Windsurf ยังรองรับไฟล์ .windsurfrules ที่ root ของ workspace และกฎแบบ global ที่ ~/.codeium/windsurf/memories/global_rules.md แต่สำหรับคำสั่งเฉพาะโปรเจกต์ ควรใช้ .windsurf/rules/ ตาม เอกสารกฎและหน่วยความจำของ Windsurf

สร้างไฟล์ .windsurf/rules/apidog.md:

# การทดสอบ Apidog API

โปรเจกต์นี้มีสถานการณ์การทดสอบ Apidog รันพวกมันด้วย Apidog CLI:

    apidog run -t <scenario_id> -e <env_id> -r cli

กฎ:
- ใช้คำสั่งที่ระบุข้างต้นอย่างถูกต้อง; อย่าสร้างแฟล็กขึ้นมาเอง
  หากไม่แน่ใจ ให้รัน `apidog run --help`
- `apidog run` จะออกด้วยรหัส 0 เมื่อทุกการยืนยันผ่าน และไม่ใช่ 0
  เมื่อมีข้อผิดพลาดใดๆ ให้รายงานรหัสการออกที่แท้จริงเสมอ
- เครื่องนี้ได้รับการยืนยันตัวตนแล้วผ่าน `apidog login`
  ห้ามเพิ่ม access token ลงในคำสั่งหรือคอมมิตลงในไฟล์นี้
- หลังจากเปลี่ยนโค้ดที่เกี่ยวข้องกับ API ให้รันสถานการณ์และดำเนินการตามผลลัพธ์

อย่าเก็บ scenario_id ไว้เฉพาะในข้อความแชท เพราะข้อมูลจะหายไปเมื่อจบเซสชัน การใส่คำสั่งในไฟล์กฎทำให้คำสั่ง:

• อยู่ใน Git และตรวจสอบย้อนหลังได้
• ใช้ร่วมกันได้ทั้งทีม
• ถูกโหลดเข้าสู่บริบทของ Cascade ในทุกเซสชัน
• กลายเป็นส่วนหนึ่งของขั้นตอนแก้ไขและตรวจสอบโค้ด

ขั้นตอนที่ 2: คัดลอกคำสั่งจริงจาก Apidog

ค่า <scenario_id> และ <env_id> ไม่ควรเดาเอง ให้ Apidog สร้างคำสั่งสำหรับสถานการณ์ของคุณ

1. เปิดสถานการณ์ทดสอบใน Apidog
2. ไปที่แท็บ CI/CD
3. คัดลอกคำสั่ง apidog run ที่ Apidog สร้างให้
4. แทนที่บรรทัดตัวอย่างใน .windsurf/rules/apidog.md

คำสั่งที่ได้จะมี scenario ID, environment ID และ reporter ที่ตรงกับโปรเจกต์ของคุณ เช่น:

apidog run -t <scenario_id> -e <env_id> -r cli

ดูรายละเอียดแฟล็กที่รองรับได้จาก เอกสารอ้างอิงคำสั่ง apidog run

ขั้นตอนที่ 3: ให้ Cascade รันการทดสอบ

เปิด Cascade ใน repository เดียวกับไฟล์กฎ จากนั้นสั่งให้รันการตรวจสอบได้โดยตรง:

รันสถานการณ์ Apidog และบอกรหัสการออกให้ฉันทราบ

Cascade ควรใช้คำสั่ง apidog run จาก .windsurf/rules/apidog.md ไม่ใช่สร้างคำสั่งใหม่เอง

การทำงานโดยไม่ต้องอนุมัติขึ้นอยู่กับระดับการทำงานอัตโนมัติของ Windsurf:

• Disabled: ทุกคำสั่งต้องได้รับการอนุมัติ
• Allowlist Only: รันอัตโนมัติเฉพาะคำสั่งใน allowlist
• Auto: Windsurf ตัดสินใจตามการตั้งค่า
• Turbo: รันอัตโนมัติทุกอย่าง ยกเว้นคำสั่งใน denylist

หากต้องการให้ apidog run รันได้โดยไม่ต้องเปิดสิทธิ์กว้างเกินไป ให้เพิ่ม apidog ในค่า windsurf.cascadeCommandsAllowList ผ่าน Command Palette > Open Settings

การตั้งค่าที่เกี่ยวข้องคือ:

windsurf.cascadeCommandsAllowList
windsurf.cascadeCommandsDenyList

หากคำสั่งตรงกับทั้ง allowlist และ denylist นโยบาย denylist จะมีผล ดูรายละเอียดเพิ่มเติมได้จาก เอกสารเทอร์มินัลของ Windsurf

สำหรับสถานการณ์แบบอ่านอย่างเดียวที่รันกับ staging การเพิ่ม apidog ใน allowlist ช่วยให้ Cascade ตรวจสอบ API ได้โดยไม่ต้องอนุมัติทุกครั้ง

ขั้นตอนที่ 4: อ่านรายงานใน Windsurf

ใช้ reporter แบบ cli เพื่อให้ Cascade อ่านผลลัพธ์จากเทอร์มินัลได้โดยตรง:

apidog run -t <scenario_id> -e <env_id> -r cli

เมื่อการทดสอบล้มเหลว รายงาน CLI จะแสดงรายละเอียด เช่น:

• คำขอที่รัน
• การยืนยันแต่ละรายการ
• status code ที่ไม่ตรงเงื่อนไข
• ฟิลด์ที่ขาดหายไป
• ค่าที่คาดหวังเทียบกับค่าจริง

ข้อมูลนี้ช่วยให้ Cascade ระบุจุดที่ต้องแก้ไขก่อนรันใหม่ได้

หากต้องการรายงานที่เปิดในเบราว์เซอร์หรือแชร์ให้ทีมได้ ให้เพิ่ม HTML reporter:

apidog run -t <scenario_id> -e <env_id> -r cli,html

Reporter แบบ html จะสร้างรายงานแบบ self-contained ใน ./apidog-reports ควรเก็บ cli ไว้เสมอ เพื่อให้ Cascade ยังอ่านผลลัพธ์แบบ inline และตัดสินใจขั้นตอนถัดไปได้

สำหรับ reporter อื่น ๆ รวมถึง JUnit สำหรับ CI dashboard โปรดดู:

• คู่มือ Apidog CLI ฉบับสมบูรณ์
• วิธีอ่านรายงานการทดสอบ Apidog CLI

ทำให้การทดสอบ API อยู่ในวงรอบของ Cascade

เป้าหมายคือให้ Cascade รันการทดสอบเองหลังแก้ไขโค้ดที่เกี่ยวข้องกับ API

ตัวอย่าง: Cascade แก้ไข handler ที่สร้าง response สำหรับการชำระเงิน หลังแก้ไขเสร็จ มันควร:

1. รันสถานการณ์ Apidog กับ staging
2. อ่าน exit code
3. ดำเนินการต่อเมื่อ exit code เป็น 0
4. เปิดอ่านรายงานเมื่อ exit code ไม่เป็น 0
5. แก้ไขจาก assertion ที่ล้มเหลว
6. รันสถานการณ์เดิมซ้ำ

apidog run ให้สัญญาณที่ชัดเจนสำหรับวงรอบนี้:

Exit code	ความหมาย	การดำเนินการ
0	ทุก assertion ผ่าน	ทำงานขั้นถัดไป
ไม่ใช่ 0	มี assertion หรือการรันที่ล้มเหลว	อ่านรายงาน แก้ไข และรันซ้ำ

นี่คือรูปแบบ delegate-then-verify: ให้เอเจนต์รันคำสั่งและอ่านผลลัพธ์ แต่ยังคงให้มนุษย์เป็นผู้สร้างสถานการณ์ทดสอบและตรวจสอบการตัดสินใจของเอเจนต์

ดูแนวทางที่เกี่ยวข้องเพิ่มเติมได้ที่:

• วิธีใช้เอเจนต์ AI สำหรับการทดสอบ API
• เครื่องมือทดสอบ Apidog AI

ตรวจสอบว่า Cascade รัน CLI จริง

อย่ายึดเฉพาะข้อความสรุปของเอเจนต์ ให้ตรวจสอบสามจุดต่อไปนี้

1. ยืนยันว่ามีการรันคำสั่ง

ดูเทอร์มินัลของ Cascade และค้นหาบรรทัด:

apidog run ...

จากนั้นตรวจสอบเอาต์พุตที่ตามมา หาก Cascade รายงานว่ารันการทดสอบแล้ว แต่ไม่มีคำสั่งหรือผลลัพธ์ในเทอร์มินัล ให้สั่งรันใหม่พร้อมขอ raw output

2. ถามหา exit code โดยตรง

ใช้คำสั่งนี้ใน Cascade:

รหัสการออกของคำสั่ง apidog run นั้นคืออะไร?

apidog run จะคืนค่า 0 เมื่อทุก assertion ผ่าน และคืนค่าที่ไม่ใช่ 0 เมื่อมีข้อผิดพลาด หากข้อความสรุประบุว่า “tests passed” แต่ exit code ไม่ใช่ศูนย์ ให้เชื่อ exit code

3. ยืนยัน scenario และ environment ที่ใช้

หากพบข้อความ scenario not found Cascade อาจใช้ ID ที่ผิด ตรวจสอบค่า -t และ -e ในสามตำแหน่ง:

1. คำสั่งที่ Apidog สร้างในแท็บ CI/CD
2. ไฟล์ .windsurf/rules/apidog.md
3. คำสั่งที่ Cascade รันจริงในเทอร์มินัล

ไฟล์กฎควรเป็นแหล่งข้อมูลอ้างอิงเดียวสำหรับคำสั่งที่ Cascade ต้องใช้

ทางเลือก: เชื่อมต่อ Apidog MCP Server

การรัน apidog run จากกฎเพียงอย่างเดียวครอบคลุมการตรวจสอบ API ส่วนใหญ่แล้ว หากต้องการให้ Cascade เข้าถึงข้อมูล API specification ระหว่างเขียนโค้ด ให้เชื่อมต่อ MCP server เพิ่มเติม

Windsurf รองรับ Model Context Protocol และอ่านรายการ server จาก:

~/.codeium/windsurf/mcp_config.json

คุณสามารถแก้ไขไฟล์โดยตรงหรือจัดการผ่าน Cascade MCP panel ดูรูปแบบการตั้งค่าได้จาก เอกสาร MCP ของ Windsurf

สำหรับการตั้งค่าเพิ่มเติม ดู:

• วิธีตั้งค่าเซิร์ฟเวอร์ MCP ใน Windsurf
• เซิร์ฟเวอร์ Apidog MCP

การแบ่งหน้าที่ควรชัดเจน:

• Apidog CLI: รันสถานการณ์และรายงานผลการทดสอบ
• Apidog MCP Server: เปิดเผย API specification เพื่อให้ Cascade อ่าน schema ระหว่างพัฒนา

แก้ปัญหาที่พบบ่อย

Cascade ไม่สนใจกฎ

ตรวจสอบว่าไฟล์กฎ:

• อยู่ที่ .windsurf/rules/ ใน root ของ repository
• มีนามสกุล .md
• มีขนาดไม่เกิน 12,000 ตัวอักษรต่อไฟล์
• ถูกโหลดใหม่หลังรีสตาร์ท Cascade

หาก Cascade รันคำสั่งทั่วไปแทนคำสั่งในกฎ ให้ตรวจสอบ path และชื่อไฟล์ก่อน

Cascade เพิ่ม access token ลงในคำสั่ง

อย่าใส่ token จริงในไฟล์กฎหรือ commit ลง Git หากเครื่องผ่าน apidog login แล้ว ให้ย้ำในกฎว่าไม่ต้องส่ง token ผ่าน command line

ดูรายละเอียดกลไกการยืนยันตัวตนได้จาก คู่มือการยืนยันตัวตน Apidog CLI

Cascade สร้างแฟล็กที่ไม่มีอยู่จริง

หากพบข้อผิดพลาด unknown option ให้สั่ง Cascade รัน:

apidog run --help

จากนั้นใช้เฉพาะแฟล็กที่แสดงใน help output ของ CLI เวอร์ชันที่ติดตั้งอยู่

Cascade รายงานว่าผ่าน แต่การรันล้มเหลว

ใช้ exit code เป็นตัวตัดสินเสมอ:

0      = ผ่าน
ไม่ใช่ 0 = ล้มเหลว

ให้เก็บกฎนี้ไว้ทั้งใน .windsurf/rules/apidog.md และขั้นตอนตรวจสอบของทีม

สรุป

ติดตั้ง apidog-cli เพียงครั้งเดียวตาม คู่มือการติดตั้ง แล้วเพิ่มกฎสั้น ๆ ใน .windsurf/rules/apidog.md จากนั้น Cascade จะรู้วิธีรันการทดสอบ API และอ่านผลลัพธ์ในวงรอบเดียวกับที่ใช้แก้ไขโค้ด

การทดสอบที่อยู่ใน GUI ต้องรอให้มนุษย์คลิก แต่คำสั่ง apidog run สามารถทำงานได้ทุกครั้งที่ Cascade แก้ไขโค้ดที่เกี่ยวข้องกับ API คุณยังคงสร้างสถานการณ์แบบภาพใน Apidog ขณะที่เอเจนต์นำสถานการณ์นั้นไปรันจากเทอร์มินัล

เมื่อคำสั่งเดียวกันทำงานในเครื่องได้แล้ว ให้ใช้ต่อใน CI ด้วย Apidog CLI ใน GitHub Actions ซึ่งครอบคลุม secrets, reporters และการควบคุมด้วย exit code

ดาวน์โหลด Apidog สร้างหนึ่งสถานการณ์ คัดลอกคำสั่ง apidog run ลงในกฎของ Windsurf แล้วให้ Cascade ตรวจสอบ API ในการเปลี่ยนแปลงครั้งถัดไป