DEV Community

Cover image for Hướng Dẫn Kiểm Thử API Bằng Insomnia
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Hướng Dẫn Kiểm Thử API Bằng Insomnia

Insomnia là một API client do Kong phát triển để gửi request và kiểm tra response. Công cụ này hỗ trợ HTTP, REST, GraphQL, gRPC, SOAP và WebSocket trong cùng một giao diện, phù hợp khi bạn cần một client gọn nhẹ nhưng vẫn đủ chức năng để debug và kiểm thử API thực tế.

Thử Apidog ngay hôm nay

Bài viết này hướng dẫn cách kiểm thử API trong Insomnia theo quy trình thực hành: tạo collection, gửi request, cấu hình body/query/header/auth, dùng environment để chuyển đổi base_url và token, viết test suite với assertions, sau đó chạy test bằng CLI trong CI.

Cài đặt Insomnia và tạo request đầu tiên

Tải Insomnia từ trang web chính thức của Kong và cài đặt theo hệ điều hành của bạn.

Khi mở lần đầu, Insomnia có thể hỏi bạn có muốn đăng nhập hay không. Nếu chỉ muốn làm việc cục bộ, bạn có thể chọn chế độ local/Scratch Pad tùy phiên bản. Đồng bộ đám mây là tùy chọn và sẽ được nhắc lại ở phần cuối bài.

Insomnia tổ chức request theo:

  • Collection: nhóm request dùng để debug/test API.
  • Document: thường dùng khi làm việc với API spec hoặc thiết kế API.

Để tạo request:

  1. Nhấn Create.
  2. Chọn Request Collection.
  3. Đặt tên, ví dụ: User API tests.
  4. Trong collection, nhấn +.
  5. Chọn HTTP Request.
  6. Chọn method GET.
  7. Nhập endpoint sau: 
GET https://jsonplaceholder.typicode.com/users/1
Enter fullscreen mode Exit fullscreen mode

Nhấn Send.

Insomnia sẽ hiển thị:

  • HTTP status code
  • Response body
  • Response time
  • Response size
  • Headers
  • JSON được format tự động

Với response lớn, bạn có thể dùng JSONPath hoặc XPath để lọc nội dung cần kiểm tra.

Cấu hình method, query, body, headers và auth

Với API thực tế, bạn thường cần cấu hình nhiều hơn một URL. Insomnia đặt các phần cấu hình này trong các tab bên dưới thanh URL.

Gửi JSON body với POST

Ví dụ tạo user bằng POST:

POST https://jsonplaceholder.typicode.com/users
Enter fullscreen mode Exit fullscreen mode

Trong tab Body, chọn JSON, sau đó nhập payload:

{
  "name": "Daniel Okafor",
  "email": "daniel.okafor@example.com"
}
Enter fullscreen mode Exit fullscreen mode

Khi chọn JSON, Insomnia sẽ tự đặt header:

Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

Thêm query parameters

Thay vì sửa URL thủ công như:

GET /users?page=1&limit=10&sort=name
Enter fullscreen mode Exit fullscreen mode

hãy dùng tab Query:

Key Value
page 1
limit 10
sort name

Cách này dễ đọc hơn và bạn có thể bật/tắt từng parameter khi debug.

Thêm headers

Dùng tab Headers cho các header như:

Accept: application/json
X-Request-Id: debug-001
Enter fullscreen mode Exit fullscreen mode

Nếu API yêu cầu định dạng response cụ thể, hãy đặt Accept. Nếu backend cần trace request, hãy thêm X-Request-Id hoặc header tương ứng theo hệ thống của bạn.

Cấu hình authentication

Tab Auth hỗ trợ nhiều cơ chế xác thực, gồm:

  • Bearer Token
  • Basic Auth
  • API Key
  • OAuth 1.0 / OAuth 2.0
  • AWS IAM
  • Các kiểu auth khác

Ví dụ với Bearer Token:

  1. Mở tab Auth.
  2. Chọn Bearer Token.
  3. Nhập token.

Không nên hard-code token trong từng request. Thay vào đó, dùng environment variable như:

{{ _.auth_token }}
Enter fullscreen mode Exit fullscreen mode

Nếu bạn cần chuẩn hóa status code cho API REST, tham khảo thêm bài viết về các mã trạng thái HTTP mà REST API nên sử dụng.

Thiết lập environment và biến

Environment giúp bạn tránh lặp lại URL, token và các giá trị cấu hình giữa nhiều request.

Ví dụ bạn có hai môi trường:

  • dev
  • prod

Mở menu environment ở đầu sidebar, chọn Manage Environments, sau đó cấu hình Base Environment hoặc environment con.

Ví dụ:

{
  "base_url": "https://jsonplaceholder.typicode.com",
  "auth_token": "your-token-here"
}
Enter fullscreen mode Exit fullscreen mode

Sau đó thay URL hard-code:

GET https://jsonplaceholder.typicode.com/users/1
Enter fullscreen mode Exit fullscreen mode

bằng biến:

GET {{ _.base_url }}/users/1
Enter fullscreen mode Exit fullscreen mode

Với token, trong tab Auth hoặc Headers, dùng:

Authorization: Bearer {{ _.auth_token }}
Enter fullscreen mode Exit fullscreen mode

Khi chuyển environment từ dropdown, tất cả request dùng biến sẽ tự cập nhật.

Dùng template tags để lấy dữ liệu động

Insomnia hỗ trợ template tags để tạo hoặc lấy giá trị động, ví dụ:

  • Timestamp
  • UUID
  • Giá trị từ response của request trước
  • Token đăng nhập

Một workflow phổ biến:

  1. Gửi request login.
  2. Lấy token từ response bằng JSONPath, ví dụ $.token.
  3. Dùng token đó trong header Authorization của các request tiếp theo.

Ví dụ ý tưởng response login:

{
  "token": "abc.def.ghi"
}
Enter fullscreen mode Exit fullscreen mode

Bạn có thể cấu hình template tag để lấy $.token, sau đó dùng trong header:

Authorization: Bearer <token được trích xuất>
Enter fullscreen mode Exit fullscreen mode

Cách này giúp xâu chuỗi request mà không cần viết nhiều code glue. Nếu bạn đang thiết kế các nhóm kiểm thử liên quan, xem thêm hướng dẫn về ví dụ trường hợp kiểm thử API.

Viết test suite với assertions

Gửi request thủ công chỉ cho bạn biết response hiện tại. Để kiểm tra tự động, dùng Test Suites của Insomnia, đôi khi hiển thị dưới tên Unit Tests trong collection.

Quy trình cơ bản:

  1. Mở collection.
  2. Chuyển sang tab hoặc view Tests.
  3. Tạo một test suite.
  4. Thêm test case.
  5. Chọn request mà test sẽ chạy.
  6. Viết assertion bằng JavaScript.

Insomnia dùng thư viện assertion Chai và cung cấp helper insomnia.send() để gửi request.

Ví dụ kiểm tra status code:

const response = await insomnia.send();

expect(response.status).to.equal(200);
Enter fullscreen mode Exit fullscreen mode

Ví dụ kiểm tra response body:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body).to.have.property("id");
expect(body.email).to.equal("Sincere@april.biz");
Enter fullscreen mode Exit fullscreen mode

Với endpoint:

GET https://jsonplaceholder.typicode.com/users/1
Enter fullscreen mode Exit fullscreen mode

response mẫu có trường email, nên assertion trên có thể dùng để kiểm tra dữ liệu trả về.

Một số assertion thực tế

Kiểm tra status thành công:

expect(response.status).to.equal(200);
Enter fullscreen mode Exit fullscreen mode

Kiểm tra response là JSON hợp lệ:

const body = JSON.parse(response.data);
expect(body).to.be.an("object");
Enter fullscreen mode Exit fullscreen mode

Kiểm tra field bắt buộc tồn tại:

expect(body).to.have.property("id");
expect(body).to.have.property("name");
expect(body).to.have.property("email");
Enter fullscreen mode Exit fullscreen mode

Kiểm tra header:

expect(response.headers["content-type"]).to.include("application/json");
Enter fullscreen mode Exit fullscreen mode

Kiểm tra mảng không rỗng:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(body).to.be.an("array");
expect(body.length).to.be.greaterThan(0);
Enter fullscreen mode Exit fullscreen mode

Tổ chức test suite

Khi số lượng test tăng, nên tổ chức theo tài nguyên hoặc domain logic:

User API tests
├── GET /users returns user list
├── GET /users/:id returns user detail
├── GET /users/:id returns 404 when user does not exist
└── POST /users validates required fields
Enter fullscreen mode Exit fullscreen mode

Một nguyên tắc thực tế: mỗi test chỉ nên kiểm tra một hành vi chính.

Ví dụ không nên gom tất cả vào một test lớn:

Create user, get user, update user, delete user
Enter fullscreen mode Exit fullscreen mode

Thay vào đó, tách thành các test nhỏ. Khi thất bại, bạn sẽ biết chính xác hành vi nào bị lỗi.

Để tìm hiểu thêm về nội dung nên kiểm tra, xem bài viết về các xác nhận API và cách tổ chức test suites cho tự động hóa kiểm thử API.

Chạy test từ dòng lệnh với Inso

GUI phù hợp khi phát triển và debug. Nhưng nếu muốn đưa API test vào CI/CD, bạn cần chạy test ở chế độ headless.

Insomnia có CLI tên là Inso.

Sau khi export hoặc đồng bộ collection, bạn có thể chạy test từ terminal:

inso run test "User API tests"
Enter fullscreen mode Exit fullscreen mode

Nếu có test thất bại, Inso trả về exit code khác 0. Đây là hành vi phù hợp cho CI vì pipeline có thể tự đánh dấu build là failed.

Ví dụ workflow đơn giản:

inso run test "User API tests"

if [ $? -ne 0 ]; then
  echo "API tests failed"
  exit 1
fi
Enter fullscreen mode Exit fullscreen mode

Trong GitHub Actions, bạn có thể đặt lệnh này trong step chạy test sau khi cài Inso và chuẩn bị collection.

Mô hình chung:

name: API Tests

on:
  push:
    branches:
      - main

jobs:
  api-tests:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Insomnia tests
        run: |
          inso run test "User API tests"
Enter fullscreen mode Exit fullscreen mode

Tùy cách bạn quản lý collection, bạn có thể cần thêm bước cài Inso hoặc trỏ đến file export. Bài viết về tự động hóa kiểm thử API trong CI/CD trình bày mô hình tổng quát có thể áp dụng cho Inso.

Ngoài chạy test, Inso cũng có thể dùng để lint API spec và tạo báo cáo test ở các định dạng tiêu chuẩn.

Thay đổi cloud của Insomnia 8 và lựa chọn thay thế

Insomnia 8 chuyển sang mô hình ưu tiên cloud, khuyến khích người dùng tạo tài khoản Kong và lưu project trên đám mây. Điều này khiến một phần cộng đồng không hài lòng, đặc biệt với các nhóm trước đó quen làm việc hoàn toàn local hoặc có yêu cầu dữ liệu không được rời khỏi hạ tầng nội bộ.

Các bản phát hành sau đã làm rõ hơn tùy chọn local hoặc Scratch Pad, nhưng thay đổi này vẫn khiến một số nhóm đánh giá lại quy trình công cụ API của mình.

Nếu bạn cần một nền tảng API tích hợp nhiều bước trong cùng một nơi, Apidog là một lựa chọn đáng xem xét. Apidog kết hợp thiết kế API, debug, mocking, testing và documentation. Công cụ này cũng hỗ trợ import export từ Insomnia để bạn không phải bắt đầu lại từ đầu.

Một điểm hữu ích là bạn có thể xây dựng assertion bằng giao diện trực quan mà không bắt buộc viết JavaScript, đồng thời vẫn có thể dùng script khi cần. Vì API spec, test data và mock server nằm trong cùng một project, việc giữ test đồng bộ với hợp đồng API sẽ dễ quản lý hơn.

Bạn có thể tải Apidog và import collection Insomnia để so sánh trực tiếp. Nếu muốn xem thêm các lựa chọn khác, danh sách các công cụ kiểm thử API trực tuyến miễn phí cũng là một điểm bắt đầu tốt.

Insomnia vẫn là một API client mạnh, tập trung và gọn nhẹ, đặc biệt phù hợp cho nhà phát triển độc lập hoặc nhóm nhỏ muốn debug nhanh. Lựa chọn cuối cùng phụ thuộc vào cách nhóm của bạn quản lý vòng đời API: dùng nhiều công cụ riêng biệt hay gom thiết kế, mock, test và tài liệu vào cùng một nền tảng.

Các câu hỏi thường gặp

Insomnia có miễn phí để sử dụng không?

Có. Insomnia có gói miễn phí cho nhu cầu cá nhân, bao gồm gửi request và chạy test suite cục bộ. Các gói trả phí bổ sung tính năng cộng tác nhóm và giới hạn đồng bộ cloud lớn hơn. Các phiên bản gần đây cũng cho phép làm việc local nếu bạn không muốn dùng cloud sync.

Insomnia hỗ trợ những giao thức nào?

Insomnia hỗ trợ HTTP, REST, GraphQL, gRPC, SOAP và WebSocket. Cách cấu hình request khác nhau theo giao thức, nhưng workflow gửi request, kiểm tra response và viết test vẫn khá nhất quán, đặc biệt với API dựa trên HTTP.

Làm cách nào để viết assertion trong Insomnia?

Dùng tính năng Test Suites. Mở collection, vào view Tests, tạo test suite, thêm test và chọn request cần chạy. Trong test, gọi:

const response = await insomnia.send();
Enter fullscreen mode Exit fullscreen mode

Sau đó dùng expect theo cú pháp Chai:

expect(response.status).to.equal(200);
Enter fullscreen mode Exit fullscreen mode

Nếu cần kiểm tra body JSON:

const body = JSON.parse(response.data);
expect(body).to.have.property("id");
Enter fullscreen mode Exit fullscreen mode

Điều gì đã thay đổi trong Insomnia 8?

Insomnia 8 chuyển sang mặc định ưu tiên cloud, nhắc người dùng đăng nhập tài khoản Kong và đồng bộ project lên đám mây. Một số người dùng không thích thay đổi này vì các phiên bản trước thân thiện hơn với workflow hoàn toàn local. Các bản cập nhật sau đã bổ sung hoặc làm rõ tùy chọn local, nhưng thay đổi này vẫn khiến nhiều nhóm cân nhắc lựa chọn thay thế.

Tôi có thể chạy test Insomnia trong CI không?

Có. Dùng CLI Inso. Sau khi export hoặc đồng bộ collection, chạy:

inso run test "<tên test suite>"
Enter fullscreen mode Exit fullscreen mode

Nếu test thất bại, Inso trả về exit code khác 0, nên CI có thể tự động fail build khi API test không đạt.

Top comments (0)