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

Trae คือวงจรการทำงานที่ Builder agent อ่าน repository, แก้ไขไฟล์, รันคำสั่งในเทอร์มินัล และใช้ผลลัพธ์เพื่อตัดสินใจขั้นถัดไป แต่หากการทดสอบ API ยังอยู่หลัง GUI ใน Apidog เอดเจนต์จะไม่สามารถเรียกใช้หรือใช้ผลลัพธ์ของการทดสอบได้ การตั้งค่า Apidog CLI ให้ Trae ใช้งานจึงทำให้การทดสอบ API เข้าสู่วงจรแก้ไข–ทดสอบ–แก้ไขเดียวกับ unit tests ได้

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

วิธีทำคือเพิ่มกฎโปรเจกต์เพียงไฟล์เดียว Apidog CLI คือแพ็กเกจ npm ชื่อ apidog-cli ที่ใช้รันสถานการณ์ทดสอบที่สร้างใน Apidog จากเทอร์มินัลได้โดยตรง เมื่อ CLI พร้อมใช้งานและ Trae รู้คำสั่งที่ต้องรัน Builder จะเรียกสถานการณ์ทดสอบ, อ่าน exit code และแก้โค้ดต่อเมื่อผลลัพธ์ล้มเหลว

หากยังไม่ได้ติดตั้ง CLI ให้เริ่มจาก วิธีติดตั้ง Apidog CLI ด้วย AI coding agent ซึ่งครอบคลุมการติดตั้งด้วย npm, การรับรองความถูกต้อง และการรันครั้งแรก บทความนี้สมมติว่าคำสั่งต่อไปนี้ทำงานแล้ว:

apidog --version

และเครื่องของคุณผ่านการรับรองความถูกต้องกับบัญชี Apidog แล้ว

Trae ที่กล่าวถึงในบทความนี้

Trae คือ AI IDE ของ ByteDance ที่สร้างบน VS Code และมี agent mode ชื่อ Builder ซึ่งแก้ไขไฟล์และรันคำสั่งเทอร์มินัลได้ คุณดูรายละเอียดเพิ่มเติมได้ที่ เว็บไซต์อย่างเป็นทางการของ Trae

บทความนี้กล่าวถึง Trae Desktop IDE ไม่ใช่โปรเจกต์วิจัย trae-agent แบบสแตนด์อโลนบน GitHub หากใน Trae ของคุณมีแผงแชทข้าง editor และสามารถเลือก agent เป็น Builder ได้ แสดงว่าคุณกำลังใช้เครื่องมือที่บทความนี้กล่าวถึง

Trae มีกลไกสำหรับอ่านกฎของโปรเจกต์ก่อนเริ่มทำงาน กลไกนี้ช่วยเปลี่ยนคำสั่งแบบครั้งเดียว เช่น “รันการทดสอบ API” ให้กลายเป็นขั้นตอนที่ Builder เรียกใช้ได้อย่างต่อเนื่อง หากต้องการทำความเข้าใจ CLI โดยไม่ผูกกับ IDE ใด IDE หนึ่งก่อน ดู คู่มือ Apidog CLI ฉบับสมบูรณ์

ขั้นตอนที่ 1: เพิ่มไฟล์กฎของโปรเจกต์

Trae อ่านไฟล์กฎก่อนที่ Builder จะเริ่มทำงาน สำหรับกฎระดับโปรเจกต์ ให้สร้างไฟล์นี้ที่ root ของ repository:

.trae/rules/project_rules.md

ตาม เอกสารกฎของ Trae agent จะโหลดกฎระหว่างเริ่มต้นและอ้างอิงกฎเหล่านี้ขณะสร้างหรือแก้ไขโค้ด แม้ Trae จะรองรับ user_rules.md สำหรับกฎที่ใช้ร่วมกันทุกโปรเจกต์ แต่สำหรับ workflow นี้ กฎระดับโปรเจกต์เพียงไฟล์เดียวก็เพียงพอ

สร้างไฟล์ .trae/rules/project_rules.md แล้วเพิ่มเนื้อหาต่อไปนี้:

## การทดสอบ API ด้วย Apidog CLI

เมื่อคุณเปลี่ยนโค้ดที่เกี่ยวข้องกับ API endpoint ให้ตรวจสอบโดยการรัน
สถานการณ์การทดสอบ Apidog ไม่ใช่แค่การทดสอบหน่วย (unit tests)

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

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

การเก็บคำสั่งไว้ใน project_rules.md ดีกว่าพิมพ์ไว้ในแชท เพราะข้อมูลในแชทจะหายไปเมื่อเซสชันสิ้นสุด แต่ไฟล์กฎจะอยู่ใน repository สำหรับเพื่อนร่วมทีมและการทำงานของ Builder ในอนาคต

สำหรับ monorepo คุณยังสามารถวางโฟลเดอร์ .trae/rules/ ไว้ในไดเรกทอรีย่อยของแต่ละบริการ เพื่อกำหนดคำสั่งทดสอบ API แยกตามบริการได้

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

ไม่ต้องเดา scenario ID หรือ environment ID เอง ให้เปิดสถานการณ์ทดสอบใน Apidog แล้วไปที่แท็บ CI/CD จากนั้นคัดลอกคำสั่ง apidog run ที่ระบบสร้างให้

คำสั่งนั้นมีค่าที่ถูกต้องอยู่แล้ว:

• scenario ID อยู่หลัง -t
• environment ID อยู่หลัง -e

นำค่าจริงมาแทนที่ placeholder ใน .trae/rules/project_rules.md:

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

ตัวอย่างหลังแทนค่าแล้ว:

apidog run -t your_scenario_id -e your_environment_id -r cli

สำหรับรายการแฟล็กทั้งหมดและความหมายของแต่ละแฟล็ก ดู การอ้างอิงคำสั่ง apidog run

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

เมื่อเพิ่มกฎแล้ว ให้เลือก agent เป็น Builder และเริ่มทำงานใน repository นั้น Builder จะโหลด project_rules.md ตอนเริ่มต้น จึงรู้ว่าต้องใช้ Apidog CLI สำหรับการเปลี่ยนแปลงที่กระทบ API

คุณสามารถแก้โค้ดที่เกี่ยวข้องกับ API แล้วให้ Builder ตรวจสอบเอง หรือสั่งโดยตรง:

Run the Apidog test scenario and tell me the exit code.

Builder จะเสนอคำสั่ง apidog run ตามที่ระบุในไฟล์กฎ โมเดลการอนุมัติของ Trae มีความสำคัญ: เมื่อ agent ต้องการรัน shell command ระบบจะแสดงคำสั่งพร้อมปุ่ม Run และคำสั่งจะทำงานในเทอร์มินัลของ Trae หลังจากคุณอนุมัติเท่านั้น

หลังคำสั่งทำงาน Builder จะอ่าน output และวิเคราะห์ผลลัพธ์ต่อโดยอัตโนมัติ

ใช้ reporter แบบ CLI เพื่อให้ Builder อ่านผลลัพธ์จากเทอร์มินัลได้ทันที:

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

ตัวรายงาน cli แสดงผลทีละขั้นตอน รวมถึง request, assertion, สรุปผล และ exit code

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

เมื่อการรันล้มเหลว ให้ดู output จาก -r cli ในเทอร์มินัลของ Trae รายงานจะช่วยระบุ:

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

ข้อมูลนี้มักเพียงพอให้ Builder ระบุไฟล์หรือ logic ที่ต้องแก้ได้

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

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

ตัวรายงาน html จะสร้างไฟล์รายงานแบบ self-contained ใน:

./apidog-reports

ควรเก็บ cli ไว้เสมอ เพื่อให้ Builder ยังอ่านข้อความผลลัพธ์แบบ inline และตัดสินใจขั้นตอนต่อไปได้ สำหรับรูปแบบรายงานอื่น เช่น JSON และ JUnit ที่ใช้กับ CI dashboard ได้ ดู คู่มือรายงานการทดสอบ Apidog CLI

ทำให้การทดสอบเป็นส่วนหนึ่งของวงจร Trae

เป้าหมายไม่ใช่แค่สั่ง Builder ให้รันทดสอบหนึ่งครั้ง แต่คือให้ Builder รันสถานการณ์เองเมื่อมีการเปลี่ยนโค้ด API ตามกฎใน project_rules.md

ตัวอย่าง workflow สำหรับ handler ที่สร้างการตอบกลับการชำระเงิน:

1. Builder แก้ไข handler
2. Builder รันสถานการณ์ Apidog กับ environment ที่กำหนด
3. Builder อ่าน exit code และรายงาน assertion
4. หาก exit code เป็น 0 Builder จึงดำเนินงานต่อ
5. หาก exit code ไม่เป็น 0 Builder ตรวจสอบ assertion ที่ล้มเหลว แก้โค้ด แล้วรันใหม่

ด้วยวิธีนี้ การทดสอบ API จะอยู่ในวงจรเดียวกับการรัน unit tests:

แก้โค้ด → รันทดสอบ → อ่านผลลัพธ์ → แก้โค้ด → รันทดสอบซ้ำ

คุณยังคงออกแบบสถานการณ์ทดสอบด้วย UI ใน Apidog ส่วน Builder รับผิดชอบการรันและอ่านผลลัพธ์จาก CLI

แนวทางนี้เป็นรูปแบบ delegate-then-verify: ให้ agent ทำงานและอ่านผลลัพธ์ แต่คุณยังตรวจสอบว่ามันรันคำสั่งจริงและตีความ exit code ถูกต้อง สำหรับแนวทางที่กว้างขึ้น ดู วิธีใช้ AI agents สำหรับการทดสอบ API และ Apidog AI test harness

ยืนยันว่า Trae รัน CLI จริง

อย่าเชื่อเพียงข้อความสรุปของ agent ให้ตรวจสอบตามลำดับนี้

1. ตรวจสอบว่าคำสั่งถูกเรียกจริง

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

apidog run

ต้องมี output ปรากฏต่อจากคำสั่งนั้น หาก Builder รายงานว่ารันทดสอบแล้ว แต่ไม่มีคำสั่งหรือ output ในเทอร์มินัล ให้สั่งมันรันใหม่และแสดง raw output

2. ตรวจสอบ exit code

ถาม Builder โดยตรง:

What was the exit code of that apidog run command?

กฎสำคัญคือ:

• exit code 0 หมายถึง assertion ทุกข้อผ่าน
• exit code ที่ไม่ใช่ 0 หมายถึงมีข้อผิดพลาด

หาก Builder สรุปว่า “การทดสอบผ่าน” แต่ exit code ไม่เป็น 0 ให้ถือว่าการรันล้มเหลว Exit code คือค่าที่ใช้ตัดสินผลจริง

3. ตรวจสอบ scenario และ environment ที่ใช้

หากได้ข้อผิดพลาด เช่น scenario not found Builder อาจใช้ ID ผิด ให้ตรวจสอบค่าในคำสั่ง:

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

เทียบกับทั้งสองแหล่งนี้:

• .trae/rules/project_rules.md
• คำสั่งที่ Apidog สร้างในแท็บ CI/CD

ให้ถือว่า ID ในไฟล์กฎคือแหล่งอ้างอิงหลักของ Builder

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

การรัน apidog run จาก project_rules.md ครอบคลุมการตรวจสอบ API ส่วนใหญ่แล้ว แต่ MCP ช่วยให้ Builder เข้าถึงข้อมูลสเปค API ขณะเขียนโค้ดได้ด้วย

Trae ทำหน้าที่เป็น MCP client ดังนั้น Builder จึงเรียกใช้เครื่องมือจาก MCP server ได้

เพิ่ม MCP server ใน Trae ตามขั้นตอนนี้:

1. เปิดการตั้งค่า Trae
2. ไปที่แท็บ MCP
3. เลือก server จาก marketplace หรือเลือก Add Manually
4. วาง JSON configuration ที่มี command, args และ env

ดูรายละเอียดได้จาก คู่มือการเพิ่มเซิร์ฟเวอร์ MCP ของ Trae

เซิร์ฟเวอร์ Apidog MCP เปิดเผย API specification ผ่าน MCP เพื่อให้ Builder อ่าน schema ได้ขณะเขียนโค้ด

แบ่งหน้าที่ให้ชัดเจน:

• Apidog CLI: รันสถานการณ์ทดสอบและคืนผลลัพธ์
• Apidog MCP: ให้ข้อมูลสเปค API แก่ agent

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

Builder เพิกเฉยต่อไฟล์กฎ

หาก Builder รันคำสั่งทั่วไปหรือไม่รันคำสั่งเลย ให้ตรวจสอบตำแหน่งและชื่อไฟล์:

.trae/rules/project_rules.md

ตรวจสอบว่า:

• ไฟล์อยู่ที่ root ของ repository
• โฟลเดอร์ชื่อ rules ไม่ใช่ rule
• เริ่มเซสชัน Builder ใหม่หลังแก้ไขกฎ

Builder พยายามส่ง access token

หาก Builder เพิ่ม --access-token ทั้งที่เครื่องล็อกอินผ่าน apidog login แล้ว ให้ย้ำกฎนี้ใน project_rules.md:

อย่าเพิ่มแฟล็ก --access-token และอย่าใส่โทเค็นในไฟล์นี้เด็ดขาด

อย่าเก็บ token จริงใน repository สำหรับรายละเอียดการใช้ credentials แบบ interactive และ CI ดู การรับรองความถูกต้องของ Apidog CLI

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

หากได้รับข้อผิดพลาด unknown option หมายความว่า Builder เดาแฟล็กที่ Apidog CLI เวอร์ชันของคุณไม่รองรับ ให้สั่ง:

apidog run --help

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

Builder รายงานว่าผ่านทั้งที่คำสั่งล้มเหลว

ตรวจสอบ exit code เสมอ หาก summary และ exit code ขัดแย้งกัน ให้เชื่อ exit code

เพิ่มกฎนี้ไว้ใน project_rules.md เพื่อป้องกันความเข้าใจผิด:

ถือว่ารหัสออกที่ไม่เป็นศูนย์คือการทดสอบที่ล้มเหลว แม้ว่าสรุปจะดูดีก็ตาม

สรุป: เปลี่ยน agent ให้ทำงานในวงจรที่ผ่านการทดสอบ

ขั้นตอนการตั้งค่ามีเพียงไม่กี่ข้อ:

1. ติดตั้ง apidog-cli ตามคู่มือการติดตั้ง
2. คัดลอกคำสั่ง apidog run จากแท็บ CI/CD ใน Apidog
3. เพิ่มคำสั่งและกฎ exit code ลงใน .trae/rules/project_rules.md
4. ให้ Builder รันการทดสอบหลังแก้ไข API

เมื่อทำเสร็จ Builder จะรู้วิธีรันทดสอบ API และใช้ผลลัพธ์เป็นส่วนหนึ่งของการแก้โค้ด Endpoint ที่เสียจึงถูกตรวจพบระหว่างที่ agent ยังทำงานกับการเปลี่ยนแปลง ไม่ใช่หลังจาก merge หรือ deploy ไปแล้ว

สร้างสถานการณ์ทดสอบใน Apidog, วางคำสั่ง apidog run ในไฟล์กฎ แล้วให้ Builder ใช้งานในการเปลี่ยนแปลง API ครั้งถัดไป

หากต้องการรันสถานการณ์เดียวกันโดยไม่มี agent ใน CI ให้ดู Apidog CLI ใน GitHub Actions ซึ่งครอบคลุม secrets, reporters และการกำหนดเงื่อนไขจาก exit code สำหรับ pipeline CI