·

TestRail MCP với Gemini CLI

Cài đặt TestRail MCP trong Gemini CLI để AI agent có thể quản lý test case, test run và kết quả kiểm thử ngay trong trình soạn thảo.

Gemini CLI của Google là một agentic CLI có context window (cửa sổ ngữ cảnh) rất lớn — một lợi thế thực sự khi làm việc với dữ liệu TestRail, vì bạn có thể nạp cả hàng trăm case cùng lịch sử result của nhiều run vào một phiên phân tích duy nhất mà không phải chia nhỏ nhiều lần. Bài này hướng dẫn cách kết nối TestRail MCP server với Gemini CLI, cách truy vấn run/result/coverage gap (khoảng trống độ phủ), một ví dụ thực chiến tạo báo cáo release readiness (mức độ sẵn sàng phát hành), và so sánh output thực tế giữa Gemini CLI với Claude Code khi cùng xử lý một tác vụ TestRail.

Cài Đặt Và Kết Nối TestRail MCP Với Gemini CLI

Gemini CLI đọc cấu hình MCP server từ file .gemini/settings.json (cấp project) hoặc ~/.gemini/settings.json (cấp global). Khai báo TestRail MCP server:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "mcp-server-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.io",
        "TESTRAIL_EMAIL": "$TESTRAIL_EMAIL",
        "TESTRAIL_API_KEY": "$TESTRAIL_API_KEY",
        "TESTRAIL_PROJECT_ID": "12"
      },
      "trust": false
    }
  }
}

Trường trust khi để false (mặc định) nghĩa là Gemini CLI sẽ hỏi xác nhận mỗi khi gọi một tool của server này lần đầu trong phiên làm việc — bạn có thể chọn "always allow" cho tool đọc để không bị hỏi lại, nhưng nên giữ nguyên việc hỏi xác nhận cho tool ghi. Sau khi cấu hình, khởi động lại Gemini CLI và gõ /mcp list để kiểm tra trạng thái kết nối và số tool khả dụng của testrail.

Một điểm cần lưu ý riêng với Gemini CLI: biến môi trường tham chiếu bằng cú pháp $TESTRAIL_API_KEY cần được export sẵn trong shell trước khi chạy gemini, hoặc đặt trong file .env tại root project nếu bạn đã cấu hình Gemini CLI tự động load dotenv. Nếu thiếu biến, Gemini CLI thường báo lỗi kết nối MCP ngay khi khởi động thay vì lỗi muộn khi gọi tool — dấu hiệu này giúp bạn phát hiện sự cố cấu hình sớm hơn so với một số client khác.

Mẹo: Bật trust: false (mặc định) trong suốt giai đoạn onboarding TestRail MCP cho thành viên mới trong team. Việc phải xác nhận thủ công vài lần đầu giúp người mới quan sát được chính xác agent đang gọi tool nào, với tham số gì — một cách học nhanh hơn nhiều so với chỉ đọc tài liệu.

Truy Vấn Run, Result Và Coverage Gap Từ Gemini CLI

Nhờ context window lớn, Gemini CLI xử lý tốt các câu hỏi phân tích tổng hợp trên nhiều run cùng lúc — loại câu hỏi mà nếu dùng model context nhỏ hơn, bạn phải chia thành nhiều lần hỏi nhỏ. Vài ví dụ truy vấn thực tế:

Lấy toàn bộ run trong 60 ngày gần nhất của suite "Payment" (dùng testrail_get_runs
với filter created_after phù hợp), với mỗi run lấy result qua
testrail_get_results_for_run, sau đó tổng hợp:
- Case nào fail từ 3 lần trở lên trên các run khác nhau (nghi flaky hoặc bug thật).
- Case nào chưa từng xuất hiện trong bất kỳ run nào (coverage gap - khoảng trống độ phủ).
- Xu hướng tỷ lệ pass theo thời gian (tăng/giảm/ổn định).

Với câu hỏi "case nào chưa từng xuất hiện trong run nào", agent cần đối chiếu toàn bộ case trong suite (từ testrail_get_cases) với tập hợp case_ids xuất hiện trong các run đã lấy — một phép so sánh tập hợp (set difference) mà mô hình có thể thực hiện tốt trong context, miễn là toàn bộ dữ liệu vừa trong một lần nạp.

Một truy vấn khác hữu ích cho leader kỹ thuật: phân tích coverage theo priority.

Trong suite "Checkout", tính tỷ lệ phần trăm case priority=High đã có run trong
30 ngày gần nhất so với tổng case priority=High. Nếu tỷ lệ dưới 90%,
liệt kê rõ case nào đang bị bỏ sót.

Đây là loại câu hỏi rất thực tế trước mỗi release: leader không muốn nghe "tổng coverage 85%" một cách mơ hồ, mà muốn biết cụ thể case quan trọng (High priority) nào chưa được test trong chu kỳ gần nhất.

Mẹo: Khi hỏi về coverage gap, luôn chỉ rõ khung thời gian (ví dụ "30 ngày gần nhất") thay vì hỏi "case nào chưa test". TestRail lưu lịch sử run vô hạn, nên nếu không giới hạn thời gian, agent có thể tính coverage dựa trên run từ cả năm trước — cho ra số liệu coverage cao giả tạo, không phản ánh đúng tình trạng hiện tại.

Ví Dụ Thực Chiến: Tạo Báo Cáo Release Readiness

Đây là một trong những use case giá trị nhất của việc kết hợp Gemini CLI với TestRail MCP: tự động soạn báo cáo đánh giá mức độ sẵn sàng phát hành, thứ mà QA lead thường phải tổng hợp thủ công từ nhiều nguồn trước mỗi buổi go/no-go meeting.

Chuẩn bị báo cáo Release Readiness cho milestone "Release 3.2", gồm các phần:

1. Tổng số case trong scope milestone, số case Passed/Failed/Blocked/Untested
   (lấy từ run gắn với milestone này qua testrail_get_runs, filter theo milestone_id).
2. Danh sách case Failed hoặc Blocked, kèm comment gần nhất (lý do fail),
   sắp xếp theo priority giảm dần.
3. Danh sách case Untested có priority=High (rủi ro cao nhất nếu release mà chưa test).
4. Kết luận đề xuất: "Sẵn sàng release", "Sẵn sàng có điều kiện", hoặc "Chưa sẵn sàng",
   dựa trên quy tắc: nếu còn case High priority ở trạng thái Failed hoặc Untested
   thì không được kết luận "Sẵn sàng release".
5. Xuất báo cáo dạng markdown, lưu vào file reports/release-3.2-readiness.md.

Việc quy định rõ quy tắc kết luận ở bước 4 (không tự do đánh giá theo cảm tính của model) là chi tiết quan trọng nhất trong prompt này. Nếu không có quy tắc cứng, agent có thể đưa ra kết luận "có vẻ ổn" một cách chủ quan, không nhất quán giữa các lần chạy report. Khi quy tắc được viết rõ như một điều kiện logic, kết luận của report trở nên có thể kiểm chứng (verifiable) và lặp lại được (reproducible) — hai tính chất bắt buộc phải có với bất kỳ báo cáo dùng để ra quyết định release.

Mẹo: Lưu prompt báo cáo release readiness này thành một file .gemini/commands/release-readiness.toml (Gemini CLI hỗ trợ custom slash command dạng file), để mỗi lần cần chỉ cần gõ /release-readiness Release 3.2 thay vì gõ lại toàn bộ đoạn prompt dài mỗi lần.

So Sánh Output TestRail MCP Giữa Gemini CLI Và Claude Code

Cả hai công cụ đều gọi đúng cùng bộ tool MCP (mcp-server-testrail không đổi giữa client), nhưng cách chúng lập kế hoạch (planning) và trình bày kết quả có khác biệt đáng chú ý trong thực tế sử dụng:

  • Về xử lý dữ liệu lớn: với context window lớn hơn, Gemini CLI thường xử lý tốt hơn khi bạn yêu cầu phân tích nhiều run/case cùng lúc trong một prompt (ví dụ "phân tích toàn bộ 15 run trong quý"), ít bị tình trạng phải tóm tắt/cắt bớt dữ liệu giữa chừng. Claude Code, với context nhỏ hơn ở một số model, có xu hướng tự chia nhỏ thành nhiều bước gọi tool tuần tự và tóm tắt dần — kết quả cuối vẫn đúng nhưng chậm hơn.
  • Về tuân thủ quy tắc chặt trong prompt: trong thử nghiệm thực tế viết case theo template nghiêm ngặt, Claude Code có xu hướng tuân thủ format được yêu cầu (ví dụ đúng cấu trúc Steps/Expected Result) nhất quán hơn qua nhiều lần chạy lặp lại, còn Gemini CLI đôi lúc "sáng tạo" thêm field không được yêu cầu nếu prompt không tuyệt đối rõ ràng.
  • Về tốc độ với truy vấn đơn giản: cho các câu hỏi đọc dữ liệu đơn giản (ví dụ "run nào đang mở"), cả hai tương đương nhau về tốc độ và độ chính xác — sự khác biệt chỉ rõ rệt ở các tác vụ phân tích tổng hợp phức tạp hoặc tác vụ ghi dữ liệu có ràng buộc format chặt.
  • Về chi phí vận hành: nếu bạn chạy report coverage/release readiness định kỳ (hàng ngày hoặc hàng tuần) với khối lượng case lớn, chi phí token của Gemini CLI cho các tác vụ nạp nhiều dữ liệu một lần có thể cạnh tranh hơn so với việc Claude Code phải chia nhiều lượt gọi tool nhỏ — nhưng con số cụ thể phụ thuộc vào gói giá bạn đang dùng, nên luôn benchmark bằng workload thật của team trước khi quyết định công cụ chính.

Mẹo: Đừng chọn một công cụ duy nhất cho "tất cả việc TestRail". Một pattern thực tế hiệu quả: dùng Gemini CLI cho các report phân tích tổng hợp quy mô lớn (release readiness, coverage theo quý), dùng Claude Code cho việc viết case hàng ngày cần tuân thủ format chặt — tận dụng đúng điểm mạnh của từng công cụ thay vì ép một công cụ làm mọi việc.

Mẹo

Một số điểm cần chuẩn bị trước khi đưa Gemini CLI vào workflow TestRail chính thức của team:

  • Kiểm tra version mcp-server-testrail tương thích với cách Gemini CLI xử lý MCP tool schema — một số version cũ của server có schema tool không hoàn toàn tuân JSON Schema draft mà Gemini CLI yêu cầu nghiêm ngặt, dẫn đến lỗi parse tool definition.
  • Với report tự động sinh ra file markdown, luôn thêm review bước cuối bởi QA lead trước khi gửi cho stakeholder — AI tổng hợp số liệu chính xác, nhưng phần "kết luận đề xuất" vẫn nên có con người xác nhận lần cuối cho các release quan trọng.
  • Theo dõi giới hạn quota API của Gemini (tuỳ tier bạn dùng) khi chạy report định kỳ tự động qua cron job hoặc CI, tránh tình trạng report bị gián đoạn giữa kỳ do hết quota.

Mẹo: Với các report release readiness dùng để ra quyết định go/no-go, luôn đính kèm timestamp và câu "Dữ liệu được tổng hợp tự động bởi AI agent lúc [thời gian], dựa trên dữ liệu TestRail tại thời điểm đó" vào đầu report. Điều này giúp người đọc report hiểu đúng ngữ cảnh dữ liệu, tránh nhầm lẫn với báo cáo do người viết tay có thể đã bổ sung thêm nhận định định tính.

Tiếp TestRail MCP với Cursor