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

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

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

หากคุณยังไม่ได้ติดตั้ง CLI โปรดดำเนินการก่อน วิธีติดตั้ง Apidog CLI ด้วยเอเจนต์โค้ดดิ้ง AI จะอธิบายขั้นตอนการติดตั้ง npm, การตรวจสอบสิทธิ์ และการรันครั้งแรก โดยมีเอเจนต์เป็นผู้พิมพ์ บทความนี้สมมติว่า apidog --version แสดงตัวเลขและบัญชี Apidog ของคุณได้รับการยืนยันสิทธิ์แล้ว

Windsurf ที่พูดถึงนี้คืออะไร

Windsurf เป็น IDE แบบ agentic ของ Codeium และเอเจนต์ในตัวของมันชื่อ Cascade Cascade ทำงานในเครื่อง, อ่านที่เก็บโค้ดของคุณ, แก้ไขไฟล์ และรันคำสั่งเชลล์ในเทอร์มินัลในตัว โดยจะขอการอนุมัติตามการตั้งค่าการทำงานอัตโนมัติของคุณ นี่คือเอดิเตอร์และเอเจนต์ของมัน ไม่ใช่ส่วนขยายของเบราว์เซอร์หรือปลั๊กอินเติมข้อความอัตโนมัติ

หากคุณยังไม่ได้ตั้งค่า โปรดเริ่มต้นด้วย วิธีดาวน์โหลดและติดตั้ง Windsurf เมื่อ Cascade เปิดอยู่ในโปรเจกต์ของคุณแล้ว คุณสามารถสอนมันเกี่ยวกับ Apidog CLI ผ่านกลไกกฎของมันเอง ซึ่งจะเปลี่ยนการ “รันการทดสอบของฉัน” แบบครั้งเดียวให้กลายเป็นสิ่งที่ Cascade สามารถทำได้ด้วยตัวเอง

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

Cascade อ่านกฎของโปรเจกต์จากไฟล์ Markdown ก่อนที่จะเริ่มทำงาน วางไว้ในไดเรกทอรี .windsurf/rules/ ที่ root ของ repository ของคุณ โดยมีหนึ่งกฎต่อหนึ่งไฟล์ Windsurf ยังคงอ่านไฟล์ .windsurfrules แบบไฟล์เดียวที่ root ของ workspace และไฟล์ ~/.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 เมื่อมีข้อผิดพลาดใดๆ
  ให้ถือว่ารหัส 0 คือผ่าน และไม่ใช่ 0 คือไม่ผ่าน รายงานรหัสการออกที่แท้จริง
- เครื่องนี้ได้รับการยืนยันตัวตนแล้วผ่าน `apidog login` ห้ามเพิ่ม
  access token ลงในคำสั่งหรือคอมมิตไปยังไฟล์นี้
- หลังจากคุณเปลี่ยนโค้ดที่เกี่ยวข้องกับ API ให้รันสถานการณ์และดำเนินการตามผลลัพธ์

ทำไมต้องเป็นไฟล์กฎแทนที่จะเป็นข้อความแชท? ID สถานการณ์ที่พิมพ์ลงในแชทจะหายไปเมื่อเซสชันสิ้นสุดลง ID ที่อยู่ใน .windsurf/rules/apidog.md จะคงอยู่สำหรับเพื่อนร่วมทีมทุกคนและทุกเซสชัน Cascade นับจากนี้ไป มันจะคงอยู่, มีเวอร์ชันใน Git และ Cascade จะโหลดเข้าสู่บริบทโดยอัตโนมัติเมื่อเริ่มต้น

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

<scenario_id> และ <env_id> ในบล็อกนั้นไม่ใช่ตัวยึดที่คุณต้องเดา Apidog จะสร้างคำสั่งที่ถูกต้องให้คุณ

เปิดสถานการณ์การทดสอบใน Apidog ไปที่แท็บ CI/CD และคัดลอกคำสั่ง apidog run ที่เตรียมไว้แล้ว มันมี ID สถานการณ์, ID สภาพแวดล้อม และแฟล็ก reporter ที่ถูกต้องกรอกไว้แล้ว วางคำสั่งนั้นลงใน .windsurf/rules/apidog.md แทนบรรทัดตัวอย่าง ตอนนี้กฎจะมีคำสั่งที่ใช้งานได้จริงกับโปรเจกต์ของคุณ ไม่ใช่แค่เทมเพลต

สำหรับรายละเอียดทั้งหมดของคำสั่งนั้นและแฟล็กทั้งหมดที่ยอมรับ โปรดดูที่ เอกสารอ้างอิงคำสั่ง apidog run

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

เมื่อตั้งกฎเรียบร้อยแล้ว ให้เปิด Cascade ใน repo ของคุณ มันจะโหลด .windsurf/rules/apidog.md เมื่อเริ่มต้น ดังนั้นมันจึงรู้แล้วว่ามี CLI อยู่ ทำการเปลี่ยนแปลงที่เกี่ยวข้องกับ API ของคุณ หรือแค่สั่งให้มันรันการตรวจสอบ:

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

Cascade จะออกคำสั่ง apidog run จากกฎของคุณ ไม่ว่ามันจะทำงานโดยไม่ต้องแจ้งเตือนหรือไม่นั้นขึ้นอยู่กับการตั้งค่าการทำงานอัตโนมัติของคุณ Windsurf มีสี่ระดับ: Disabled (ทุกคำสั่งต้องได้รับการอนุมัติ), Allowlist Only (เฉพาะคำสั่งที่ตรงกับ allowlist ของคุณเท่านั้นที่จะทำงานอัตโนมัติ), Auto (การตัดสินใจแบบพรีเมียม) และ Turbo (ทุกอย่างทำงานอัตโนมัติยกเว้นคำสั่งที่อยู่ใน denylist) ในโหมด Turbo คำสั่ง apidog run ธรรมดาจะทำงานด้วยตัวเอง; ในโหมดที่เข้มงวดกว่า Cascade จะหยุดและถามก่อน

หากคุณต้องการให้ apidog run ทำงานอัตโนมัติโดยไม่ต้องผ่อนปรนทุกอย่าง ให้เพิ่มลงใน allowlist ของคุณ การตั้งค่าคือ windsurf.cascadeCommandsAllowList ซึ่งสามารถเข้าถึงได้จาก Command Palette ภายใต้ Open Settings; เพิ่ม apidog แล้ว Cascade จะรันคำสั่งโดยไม่ต้องถาม การตั้งค่า denylist ที่ตรงกันคือ windsurf.cascadeCommandsDenyList และ denylist จะมีผลเมื่อคำสั่งตรงกับทั้งสองรายการ ทั้งสองรายการครอบคลุมอยู่ใน เอกสารประกอบเทอร์มินัลของ Windsurf สถานการณ์แบบอ่านอย่างเดียวกับ staging เป็นคำสั่งที่ปลอดภัยในพื้นที่ทำงาน ซึ่งรายการ allowlist ถูกสร้างขึ้นมาเพื่อสิ่งนี้

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

เมื่อการรันล้มเหลว (เป็นสีแดง) รายงานจะมีคำตอบ ตัวรายงาน -r cli จะพิมพ์ผลลัพธ์ทีละขั้นตอนและสรุปในเทอร์มินัลของ Cascade: แต่ละคำขอ, แต่ละการยืนยัน และอันไหนล้มเหลวพร้อมค่าที่คาดหวังเทียบกับค่าจริง การยืนยันที่ล้มเหลวจะระบุชื่อฟิลด์หรือรหัสสถานะที่แน่นอน ซึ่งมักจะเพียงพอให้ Cascade ค้นหาวิธีแก้ไขในการผ่านครั้งถัดไป

สำหรับรายงานที่คุณสามารถเปิดในเบราว์เซอร์หรือส่งให้เพื่อนร่วมทีมได้ ให้เพิ่ม HTML reporter:

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

ตัวรายงาน html จะเขียนไฟล์แบบ self-contained ไปยัง ./apidog-reports ให้ cli อยู่ในรายการเพื่อให้ Cascade ยังคงได้รับเอาต์พุตแบบอินไลน์ที่มันอ่านเพื่อตัดสินใจขั้นตอนต่อไป สำหรับตัวรายงานทุกประเภท รวมถึงรูปแบบ JUnit ที่แดชบอร์ด CI สามารถอ่านได้ โปรดดู คู่มือ Apidog CLI ฉบับสมบูรณ์ และ วิธีอ่านรายงานการทดสอบ Apidog CLI

การทดสอบ Windsurf ภายในวงรอบของตัวเอง

ประเด็นคือจะเกิดอะไรขึ้นเมื่อคุณหยุดถามและ Cascade รันสถานการณ์ด้วยตัวเองเพราะกฎสั่งให้มันทำ

ลองนึกภาพ Cascade กำลังแก้ไขตัวจัดการที่สร้างการตอบกลับการชำระเงิน วงรอบของมันเปลี่ยนไป มันแก้ไขโค้ด จากนั้น แทนที่จะประกาศชัยชนะ มันจะรันสถานการณ์ Apidog ของคุณกับ staging, อ่านรหัสการออก และดำเนินการตามนั้น หากผ่าน (เขียว) มันจะดำเนินการต่อ หากล้มเหลว (แดง) มันจะเปิดรายงาน, อ่านว่าการยืนยันใดล้มเหลว (รหัสสถานะ, ฟิลด์ที่หายไป, ค่าที่ไม่ถูกต้อง), ลองแก้ไข และรันซ้ำ การทดสอบ API จะกลายเป็นส่วนหนึ่งของวงรอบการแก้ไข-ทดสอบ-แก้ไขแบบเดียวกันที่ Cascade ใช้รันการทดสอบยูนิตของคุณอยู่แล้ว คุณเขียนกฎเดียวและ Cascade ก็รวมคำสั่งนั้นเข้ากับวิธีการทำงานเดิมของมัน

นี่คือโมเดลการมอบหมายแล้วตรวจสอบ (delegate-then-verify) ที่ทำให้เวิร์กโฟลว์ของเอเจนต์ปลอดภัย Cascade รันคำสั่งและอ่านผลลัพธ์; คุณยังคงสร้างสถานการณ์ด้วยภาพใน Apidog และตรวจสอบว่าเอเจนต์อ่านรหัสการออกอย่างซื่อสัตย์ สำหรับรูปแบบที่กว้างขึ้น โปรดดู วิธีใช้เอเจนต์ AI สำหรับการทดสอบ API และ เครื่องมือทดสอบ Apidog AI

ตรวจสอบว่า Cascade กำลังรัน CLI จริงๆ

เอเจนต์รายงานความสำเร็จที่พวกเขาไม่ได้ทำ และ Cascade ก็ไม่มีข้อยกเว้น มีการตรวจสอบสามข้อตามลำดับความถี่ที่พวกเขาสามารถตรวจจับปัญหาได้

ประการแรก ยืนยันว่าคำสั่งทำงานหรือไม่ Cascade จะแสดงคำสั่งที่ดำเนินการและผลลัพธ์ในเทอร์มินัล มองหาบรรทัด apidog run ... และผลลัพธ์ภายใต้บรรทัดนั้น หาก Cascade บอกว่ารันการทดสอบแล้วแต่คุณไม่เห็นคำสั่ง แสดงว่ามันสรุปสิ่งที่มันไม่เคยทำไปแล้ว ขอให้มันรันอีกครั้งและแสดงเอาต์พุตดิบ

ประการที่สอง ยืนยันรหัสการออก ซึ่งเป็นสิ่งสำคัญ ถามมันโดยตรง:

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

apidog run จะออกด้วยรหัส 0 เมื่อทุกการยืนยันผ่าน และไม่ใช่ 0 เมื่อมีข้อผิดพลาดใดๆ พฤติกรรมเดียวนี้ทำให้ Cascade หรือ pipeline สามารถถือว่าการรันนั้นเป็นประตูที่ชัดเจน เมื่อคำอธิบายของ Cascade บอกว่า “tests passed” แต่รหัสการออกเป็นค่าที่ไม่ใช่ศูนย์ รหัสการออกนั้นถูกต้อง

ประการที่สาม ยืนยันว่ามันใช้สถานการณ์จริง หากการรันล้มเหลวด้วยข้อความ “scenario not found” Cascade อาจสร้างหรือจำ ID ผิด ตรวจสอบค่า -t และ -e อีกครั้งกับไฟล์กฎของคุณและคำสั่งที่ Apidog สร้างในแท็บ CI/CD ID ที่อยู่ใน .windsurf/rules/apidog.md คือความจริง

ทางเลือก: เชื่อมต่อเซิร์ฟเวอร์ Apidog MCP

การรัน apidog run จากกฎครอบคลุมสิ่งที่คุณต้องการส่วนใหญ่ หากต้องการไปอีกขั้นหนึ่ง ให้เชื่อมต่อเซิร์ฟเวอร์ MCP

Cascade รองรับ Model Context Protocol Windsurf อ่านรายการเซิร์ฟเวอร์จาก ~/.codeium/windsurf/mcp_config.json ซึ่งคุณสามารถแก้ไขโดยตรงหรือจัดการผ่านแผง Cascade MCP; รูปแบบนี้มีเอกสารประกอบอยู่ใน เอกสารอ้างอิง MCP ของ Windsurf และ วิธีตั้งค่าเซิร์ฟเวอร์ MCP ใน Windsurf จะอธิบายผ่านแผง เซิร์ฟเวอร์ Apidog MCP จะเปิดเผยข้อกำหนด API ของคุณผ่าน MCP เพื่อให้ Cascade สามารถอ่าน schema ของคุณได้ในขณะที่เขียนโค้ด ไม่ใช่แค่หลังจากนั้น การแบ่งงานชัดเจน: CLI รันการทดสอบ และ MCP ป้อนข้อมูลข้อกำหนดให้เอเจนต์

เมื่อ Windsurf ทำผิดพลาด

ความล้มเหลวบางอย่างมักเกิดขึ้นบ่อยครั้งในระหว่างการตั้งค่า

มันละเว้นกฎ หาก Cascade รันคำสั่งทั่วไปหรือไม่มีเลย กฎอาจจะไม่ได้ถูกโหลด ยืนยันว่าไฟล์อยู่ใน .windsurf/rules/ ที่ root ของ repository ของคุณและมีนามสกุล .md ไฟล์กฎแต่ละไฟล์มีขีดจำกัดที่ 12,000 ตัวอักษร ดังนั้นควรเก็บบล็อก Apidog ให้สั้น การรีสตาร์ท Cascade จะบังคับให้มีการอ่านใหม่

มันส่ง access token ไปอยู่ดี หาก Cascade พยายามเพิ่ม access token เข้าไปในคำสั่ง แสดงว่ามันเดาจากตัวอย่างสาธารณะ กฎของคุณได้บอกไว้แล้วว่าไม่ต้องทำเช่นนั้น เนื่องจากเครื่องได้รับการยืนยันตัวตนผ่าน apidog login ย้ำบรรทัดนั้น และอย่าใส่โทเค็นจริงลงในไฟล์กฎที่จะถูกคอมมิต สำหรับวิธีการทำงานของการยืนยันตัวตน โปรดดู คู่มือการยืนยันตัวตน Apidog CLI

มันสร้างแฟล็กขึ้นมาเอง ข้อผิดพลาด “unknown option” หมายความว่า Cascade เดาแฟล็กที่เวอร์ชันของคุณไม่มี สั่งให้มันรัน apidog run --help และคัดลอกแฟล็กที่ถูกต้องจากที่นั่น ซึ่งจะถูกต้องเสมอสำหรับเวอร์ชันที่คุณติดตั้ง

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

จากเอเจนต์รายวันสู่วงรอบการทดสอบ

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

การทดสอบที่อยู่เบื้องหลัง GUI จะทำงานเมื่อมนุษย์คลิก; คำสั่งบรรทัดเดียวจะทำงานเมื่อใดก็ตามที่ Cascade ตัดสินใจ คุณยังคงสร้างสถานการณ์ด้วยภาพใน Apidog และเอเจนต์ของคุณจะรันมันในที่ที่คุณไม่ได้สังเกตการณ์ หากต้องการรันคำสั่งเดียวกันใน pipeline เมื่อมันทำงานได้ในเครื่อง Apidog CLI ใน GitHub Actions ครอบคลุมถึงความลับ, reporters และการควบคุมด้วยรหัสการออก ดาวน์โหลด Apidog สร้างหนึ่งสถานการณ์ วางคำสั่ง apidog run ลงในกฎ Windsurf และดูว่า Cascade จะรับรู้ในการเปลี่ยนแปลงครั้งถัดไปได้อย่างไร