หากคุณเคยใช้ไคลเอนต์ API ของ Insomnia คุณจะมีเครื่องมือแบบกราฟิกสำหรับส่งคำขอ ออกแบบข้อมูลจำเพาะ OpenAPI และเขียนการทดสอบ แต่เครื่องมือแบบกราฟิกจะหยุดทำงานเมื่อออกจากเครื่องของคุณ เมื่อคุณต้องการให้การทดสอบเหล่านั้นทำงานภายใน CI pipeline หรือต้องการ lint ข้อมูลจำเพาะในทุก pull request คุณจะต้องมีบางอย่างที่ทำงานในเทอร์มินัล สิ่งนั้นคือ inso.
คู่มือนี้จะอธิบายว่า inso คืออะไร วิธีการติดตั้ง คำสั่งที่คุณจะใช้ในแต่ละวัน วิธีการค้นหาข้อมูลจำเพาะและคอลเลกชันของคุณ และข้อจำกัดของมัน เมื่ออ่านจบคุณจะรู้ว่า inso CLI เหมาะกับเวิร์กโฟลว์ของคุณหรือไม่ และควรเลือกใช้อะไรหากไม่เหมาะสม
inso คืออะไร?
inso คือเครื่องมือคอมมานด์ไลน์คู่กับ Insomnia ซึ่งเป็นไคลเอนต์ API แบบโอเพนซอร์สที่ปัจจุบันดูแลโดย Kong มันนำสามสิ่งหลักที่ Insomnia ทำใน UI มาทำให้เป็นสคริปต์ได้ ได้แก่ การรันการทดสอบ การรันคอลเลกชันคำขอ และการตรวจสอบความถูกต้องของข้อกำหนด API สิ่งนี้ทำให้มันเป็นสะพานเชื่อมระหว่าง Insomnia บนเดสก์ท็อปของคุณกับการตรวจสอบอัตโนมัติที่คุณต้องการใน CI/CD
สรุปสั้นๆ ว่า “inso คืออะไร”: คือวิธีที่คุณจะรันงาน Insomnia ของคุณโดยไม่ต้องเปิด Insomnia คุณชี้ไปที่เอกสารการออกแบบหรือคอลเลกชันตามชื่อ และมันจะรันกับข้อมูลเดียวกันที่แอปของคุณรู้จักอยู่แล้ว
การติดตั้ง inso CLI
มีหลายวิธีในการติดตั้งที่ระบุไว้ เลือกวิธีที่เหมาะกับวิธีการใช้งานของคุณ
Homebrew เป็นวิธีที่ง่ายที่สุดบน macOS และ Linux:
brew install inso
Docker เป็นทางเลือกที่สะอาดที่สุดสำหรับ CI runners ที่คุณไม่ต้องการจัดการ toolchain ภายในเครื่อง:
docker pull kong/inso:latest
คุณยังสามารถดาวน์โหลดโดยตรงได้ Kong เผยแพร่ไฟล์เก็บถาวรในรูปแบบ zip สำหรับ Windows, Linux และ macOS บน เว็บไซต์เอกสารของ inso CLI ซึ่งสะดวกเมื่อคุณต้องการเวอร์ชันที่แน่นอนใน build artifact
ในอดีต inso ก็ถูกเผยแพร่บน npm ในชื่อ insomnia-inso เส้นทางนั้นยังคงมีอยู่ แต่เส้นทางที่ระบุไว้และแนะนำในปัจจุบันคือ Homebrew, Docker และการดาวน์โหลดโดยตรง หากคุณกำลังตั้งค่าสิ่งใหม่ ให้เลือกวิธีเหล่านี้
ยืนยันการติดตั้งสำเร็จ:
inso --version
คำสั่งหลักของ inso
inso มีส่วนติดต่อผู้ใช้ที่เล็กและเน้นเฉพาะจุด นี่คือคำสั่งที่คุณจะใช้จริง พร้อมตัวอย่างที่จับต้องได้
inso run test
รันชุดการทดสอบยูนิตที่คุณสร้างใน Insomnia โดยใช้สภาพแวดล้อมที่ระบุชื่อ:
inso run test "Payments API tests" --env "Staging"
ทั้งชุดทดสอบและสภาพแวดล้อมจะถูกอ้างอิงด้วยชื่อ ตรงตามที่ปรากฏในข้อมูล Insomnia ของคุณ คำสั่ง inso run test จะออกด้วยค่าที่ไม่ใช่ศูนย์หากมีการยืนยันใดๆ ล้มเหลว ซึ่งทำให้สามารถใช้งานเป็น CI gate ได้
inso run collection
รันทุกคำขอในคอลเลกชันตามลำดับ โดยใช้สภาพแวดล้อมที่ระบุชื่ออีกครั้ง:
inso run collection "Checkout flow" --env "Staging"
นี่คือสิ่งที่ใกล้เคียงที่สุดกับ "เล่นทั้งโฟลเดอร์" ใน UI มันมีประโยชน์สำหรับการทดสอบ smoke test ที่คุณต้องการยืนยันว่าลำดับของปลายทางทั้งหมดตอบสนองตามที่คาดไว้
inso lint spec
ตรวจสอบความถูกต้องของเอกสารการออกแบบ OpenAPI:
inso lint spec "Orders API"
ภายใต้การทำงาน inso lint spec ใช้ Spectral ซึ่งเป็น OpenAPI และ JSON linter แบบโอเพนซอร์สจาก Stoplight นี่คือจุดแข็งที่แท้จริงที่ควรกล่าวถึงอย่างชัดเจน: คุณจะได้รับการตรวจสอบข้อกำหนดตามกฎเกณฑ์ที่แท้จริงพร้อมชุดกฎที่สมบูรณ์ ไม่ใช่แค่การตรวจสอบไวยากรณ์ผิวเผิน หากทีมของคุณให้ความสำคัญกับการบังคับใช้สไตล์ไกด์ในข้อกำหนด คำสั่งนี้คือเหตุผลที่หลายคนยังคงใช้ inso
inso export spec
ดึงเอกสารการออกแบบออกมาเป็นไฟล์บนดิสก์:
inso export spec "Orders API" --output orders.yaml
มีประโยชน์เมื่อคุณต้องการป้อนข้อมูลจำเพาะให้กับเครื่องสร้างอื่น คอมมิต snapshot หรือส่งให้เครื่องมือที่คาดหวังไฟล์ YAML ธรรมดา
inso script
รันสคริปต์ที่ระบุชื่อซึ่งกำหนดไว้ในข้อมูล Insomnia ของคุณ โดยส่งผ่านสภาพแวดล้อมด้วย ID:
inso script deploy-smoke --env env_9f2a
นี่คือช่องทางสำหรับการเชื่อมต่อขั้นตอนที่กำหนดเองของคุณ
inso ค้นหาข้อมูลจำเพาะและคอลเลกชันของคุณได้อย่างไร
นี่คือส่วนที่ทำให้หลายคนสับสน ดังนั้นจึงควรมีความแม่นยำ inso ไม่ได้จัดเก็บอะไรด้วยตัวเอง มันอ่านจากสองแหล่ง:
- ไดเรกทอรี
.insomniaในไดเรกทอรีการทำงานของคุณ นี่คือสิ่งที่ Git Sync ของ Insomnia สร้างขึ้น ดังนั้นเมื่อคุณคอมมิตโปรเจกต์ API ของคุณไปยัง repo, inso สามารถอ่านได้โดยตรงจาก checkout นี่คือรูปแบบที่คุณต้องการสำหรับ CI - ไดเรกทอรีข้อมูลแอปพลิเคชัน Insomnia หากมีการติดตั้งแอปบนเครื่อง สิ่งนี้สะดวกสำหรับการใช้งานในเครื่อง แต่ไม่มีประโยชน์สำหรับ CI runner ที่สะอาดซึ่งไม่เคยมีแอปนี้ติดตั้งอยู่
คุณสามารถระบุแหล่งที่มาได้อย่างชัดเจน:
inso lint spec "Orders API" --workingDir ./api-project
# or point at an exact source
inso run test "Payments API tests" --src ./api-project/.insomnia
โมเดลความคิดหลัก: inso อ้างอิงทุกอย่างด้วยชื่อ (หรือ ID) และชื่อเหล่านั้นจะถูกแก้ไขตามแหล่งข้อมูลใดก็ตามที่พบ หากไม่มีชื่ออยู่ในไดเรกทอรี .insomnia หรือข้อมูลแอป inso จะไม่สามารถรันได้ ไม่มีความคิดที่จะชี้ inso ไปยังไฟล์ OpenAPI ที่แยกต่างหากแล้วสั่งว่า "ทดสอบสิ่งนี้" เว้นแต่ไฟล์นั้นจะอยู่ในโครงสร้างโปรเจกต์ของ Insomnia
ตัวอย่าง CI ขั้นต่ำ
นี่คือตัวอย่างงาน GitHub Actions ที่ตรวจสอบความถูกต้องของข้อกำหนด (lint spec) และรันชุดทดสอบทุกครั้งที่มีการ push โดยใช้ไดเรกทอรี .insomnia ที่ซิงค์ด้วย Git และคอมมิตไปยัง repo:
name: ตรวจสอบ API
on: [push]
jobs:
inso:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: ติดตั้ง inso
run: |
curl -sSL https://github.com/Kong/insomnia/releases/latest/download/inso-linux-x64.zip -o inso.zip
unzip inso.zip && sudo mv inso /usr/local/bin/
- name: ตรวจสอบความถูกต้องของ Spec
run: inso lint spec "Orders API" --workingDir .
- name: รันชุดทดสอบ
run: inso run test "Payments API tests" --env "CI" --workingDir .
เนื่องจากทั้งสองคำสั่งจะออกด้วยค่าที่ไม่ใช่ศูนย์เมื่อเกิดความล้มเหลว ดังนั้นข้อกำหนดที่เสียหรือการยืนยันที่ล้มเหลวจะทำให้งานล้มเหลว นั่นคือจุดประสงค์ทั้งหมดของการย้ายการตรวจสอบเหล่านี้ออกจาก GUI
ข้อจำกัดที่แท้จริง
inso ทำได้ดีในสิ่งที่ทำ แต่มันก็มีข้อจำกัดที่ชัดเจน
มันผูกอยู่กับแหล่งข้อมูลของ Insomnia ข้อกำหนด คอลเลกชัน และชุดทดสอบของคุณจะต้องอยู่ในโปรเจกต์ Insomnia ที่แสดงผลผ่าน Git Sync หรือแอปที่ติดตั้ง หากทีมของคุณไม่ได้ใช้ Insomnia เป็นแหล่งข้อมูลที่น่าเชื่อถือ inso ก็จะไม่มีอะไรให้ดำเนินการ
ทุกสิ่งถูกอ้างอิงด้วยชื่อ ซึ่งอ่านง่ายแต่เปราะบาง หากคุณเปลี่ยนชื่อชุดทดสอบใน UI งาน CI ที่เขียนโค้ดชื่อเก่าไว้ก็จะเสียโดยไม่แจ้งให้ทราบจนกว่าจะรันครั้งถัดไป ชื่อยังต้องมีความเฉพาะเจาะจงพอที่จะแก้ไขได้อย่างชัดเจน
ขอบเขตถูกจำกัดตามการออกแบบ inso รันการทดสอบ, รันคอลเลกชัน, ตรวจสอบความถูกต้องของข้อกำหนด, ส่งออก และรันสคริปต์ มันไม่ใช่แพลตฟอร์มสำหรับออกแบบ-จำลอง-เอกสาร-ทดสอบ สำหรับสิ่งใดก็ตามที่นอกเหนือจากคำสั่งเหล่านี้ คุณจะต้องกลับไปที่ GUI หรือใช้เครื่องมืออื่น
inso เทียบกับทางเลือกแบบรวม
inso เป็นเครื่องมือคอมมานด์ไลน์ที่แข็งแกร่งเมื่อ Insomnia เป็นไคลเอนต์ของคุณอยู่แล้ว ข้อแลกเปลี่ยนคือคุณจะต้องนำชิ้นส่วนต่างๆ มาประกอบเข้าด้วยกัน: Insomnia สำหรับการออกแบบและการดีบัก, inso สำหรับ CI, กฎของ Spectral สำหรับการตรวจสอบความถูกต้อง และเครื่องมือแยกต่างหากสำหรับ mock และเอกสาร
Apidog มีแนวทางที่ตรงกันข้าม มันรวบรวมการออกแบบ, mock, เอกสารประกอบ และการทดสอบไว้ในแพลตฟอร์มเดียว และ Apidog CLI จะรันสถานการณ์ทดสอบและคอลเลกชันของคุณจากแหล่งข้อมูลเดียวกัน ด้วยการทดสอบที่ขับเคลื่อนด้วยข้อมูล รูปแบบรายงานที่หลากหลาย และการจัดการทรัพยากรและสาขาเป็นโค้ด กล่าวให้เป็นธรรม: Apidog CLI ไม่ได้มาพร้อมกับ spec linter แบบสแตนด์อโลนเหมือน inso ที่มี Spectral ดังนั้นหากการบังคับใช้สไตล์ไกด์แบบ Spectral เป็นสิ่งสำคัญของคุณ inso จะมีข้อได้เปรียบที่แท้จริงในจุดนั้น ส่วนที่ Apidog เหนือกว่าคือการรวมระบบ คุณไม่จำเป็นต้องเชื่อมต่อเครื่องมือห้าอย่างเข้าด้วยกัน
หากคุณต้องการเปรียบเทียบทั้งสองแบบตัวต่อตัว โปรดดู Apidog CLI vs inso (Insomnia CLI) หรืออ่านข้อมูลพื้นหลังเชิงลึกใน inso (Insomnia CLI) คืออะไร หากคุณตัดสินใจว่า inso ไม่ใช่ทางเลือกที่เหมาะสม บทสรุปทางเลือกที่ดีที่สุดสำหรับ inso และ คู่มือการย้ายจาก inso ไปยัง Apidog CLI จะนำคุณไปทีละขั้นตอน สำหรับบริบทที่กว้างขึ้นเกี่ยวกับไคลเอนต์ GUI เอง Apidog vs Insomnia และ วิธีใช้ Insomnia ทดสอบ API เป็นจุดเริ่มต้นที่ดี
คุณสามารถ ดาวน์โหลด Apidog ฟรี หากคุณต้องการดูแนวทางแบบรวมระบบควบคู่ไปกับการตั้งค่า inso ของคุณ