·

TestRail MCP Là Gì?

Tìm hiểu TestRail MCP là gì và cách nó giúp AI agent quản lý test case, test run và kết quả kiểm thử.

Nếu team bạn đang dùng TestRail để quản lý test case (trường hợp kiểm thử), test suite (bộ test case) và test run (lượt chạy kiểm thử), thì TestRail MCP server chính là cầu nối để AI agent — dù là Claude Code, Cursor, Gemini CLI hay OpenCode — có thể đọc và ghi dữ liệu trực tiếp vào TestRail thông qua MCP (Model Context Protocol). Nói đơn giản: thay vì bạn phải copy-paste requirement vào TestRail rồi tự tay tạo case, bạn chỉ cần mô tả yêu cầu bằng ngôn ngữ tự nhiên, agent sẽ gọi tool để tạo case, tạo run, và cập nhật kết quả — tất cả trong một phiên làm việc, không rời khỏi terminal hay IDE.

Bài này là nền tảng của cả module: hiểu rõ TestRail MCP server có những tool gì, xác thực (authentication) ra sao, AI có thể tự động hoá đến mức nào, và làm sao để dữ liệu test manual và test automation không bị "vênh" nhau khi có AI tham gia vào quy trình.

Các Tool MCP Cốt Lõi Của TestRail: Project, Suite, Case, Run Và Result

TestRail MCP server (thường được cài dưới tên package mcp-server-testrail, chạy qua npx -y mcp-server-testrail) expose (phơi ra) một tập tool tương ứng 1-1 với các entity chính trong TestRail API v2. Hiểu đúng phân cấp dữ liệu này là điều kiện bắt buộc trước khi để AI tự ý gọi tool, vì nếu prompt mơ hồ, agent rất dễ tạo case vào sai suite hoặc sai project.

Phân cấp dữ liệu trong TestRail đi từ trên xuống: Project (dự án) → Suite (bộ test case, có thể có nhiều suite trong một project nếu project dùng multiple suite mode) → Case (case, một trường hợp kiểm thử cụ thể với steps và expected result) → Run (run, một lượt thực thi một tập case cụ thể, gắn với milestone hoặc release) → Result (kết quả của từng case trong một run, có status như Passed/Failed/Blocked/Retest).

Các tool MCP tương ứng mà bạn sẽ dùng thường xuyên nhất:

  • testrail_get_projects — lấy danh sách project, dùng để agent biết project_id cần thao tác.
  • testrail_get_suites — lấy danh sách suite trong một project.
  • testrail_get_cases — lấy case theo suite, có thể filter theo section, priority, type.
  • testrail_add_case / testrail_update_case — tạo mới hoặc sửa case.
  • testrail_get_runs / testrail_add_run / testrail_close_run — quản lý run.
  • testrail_add_result_for_case — ghi kết quả (pass/fail/blocked) cho một case trong một run cụ thể.
  • testrail_get_results_for_run — đọc lại toàn bộ kết quả của một run, phục vụ báo cáo.

Ví dụ khi bạn hỏi agent: "Liệt kê toàn bộ case trong suite Checkout của project E-commerce App", agent sẽ tự chuỗi (chain) 3 tool call: testrail_get_projects → tìm project_id khớp tên "E-commerce App" → testrail_get_suites → tìm suite_id khớp "Checkout" → testrail_get_cases với suite_id đó.

Mẹo: Khi mới setup, hãy yêu cầu agent in ra project_id và suite_id dạng bảng trước khi cho nó tạo case thật. Việc xác nhận ID bằng mắt trước khi ghi dữ liệu giúp tránh tình trạng case bị tạo nhầm project — lỗi rất phổ biến khi công ty có nhiều project trùng tên module.

Xác Thực TestRail MCP: API Key, Instance URL Và Giới Hạn Theo Project

TestRail MCP server cần 3 thông tin cấu hình bắt buộc, thường truyền qua environment variable trong file cấu hình MCP của client (Claude Code, Cursor, ...):

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "mcp-server-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.io",
        "TESTRAIL_EMAIL": "qa-bot@yourcompany.com",
        "TESTRAIL_API_KEY": "your-api-key-here",
        "TESTRAIL_PROJECT_ID": "12"
      }
    }
  }
}

Về API key: vào TestRail → My Settings → API Keys → Add Key. TestRail dùng Basic Auth kết hợp email + API key (không dùng password thật), nên nếu key bị lộ, bạn chỉ cần revoke key đó mà không ảnh hưởng tài khoản đăng nhập chính. Đây là lý do bạn luôn luôn dùng API key riêng cho AI agent, không tái sử dụng key cá nhân đang login web hàng ngày — dễ audit, dễ revoke, và tách biệt hành vi của bot khỏi hành vi của người.

TESTRAIL_PROJECT_ID là optional nhưng nên set cứng (hard-code) nếu team chỉ làm việc trên 1 project chính. Việc scope theo project giúp giảm rủi ro agent "đi lạc" sang project khác khi tên case hoặc tên module trùng nhau giữa các project — một tình huống thực tế rất dễ xảy ra ở công ty có nhiều sản phẩm dùng chung 1 TestRail instance.

Một điểm cần lưu ý về quyền hạn: API key kế thừa đúng permission của user tạo key. Nếu bạn tạo một user riêng "qa-bot" với role bị giới hạn (ví dụ không có quyền xoá project, không có quyền đổi role người khác), thì dù prompt của bạn có "sai" hay agent có "ảo giác" (hallucination), thiệt hại tối đa cũng chỉ nằm trong phạm vi quyền đó. Đây là nguyên tắc least privilege (nguyên tắc đặc quyền tối thiểu) áp dụng cho AI agent.

Mẹo: Tạo riêng một user "qa-bot" trong TestRail với role custom chỉ có quyền: xem project, tạo/sửa case, tạo/đóng run, ghi result. Không cấp quyền xoá case hoặc xoá project. Agent có thể mắc lỗi, nhưng quyền hạn giới hạn sẽ chặn được hậu quả nghiêm trọng.

AI Có Thể Tự Động Hoá Gì: Viết Case, Tạo Run Và Báo Cáo Kết Quả

Ba nhóm việc AI làm tốt nhất khi tích hợp với TestRail qua MCP:

1. Viết case từ requirement/acceptance criteria. Bạn paste một đoạn user story hoặc acceptance criteria (tiêu chí chấp nhận) vào chat, agent phân tích rồi tạo bộ case gồm case chính (happy path), case biên (edge case), và case negative (input sai/lỗi). Ví dụ prompt: "Dựa vào acceptance criteria sau, tạo test case cho suite 'Login' trong TestRail, đảm bảo có ít nhất 1 case happy path, 2 case validate input sai, 1 case rate-limit: [paste AC]."

2. Tạo run và đồng bộ kết quả automation. Sau khi CI chạy xong bộ automation test, agent có thể đọc report (JUnit XML, Allure, ...) và map từng test case tự động sang case ID tương ứng trong TestRail, rồi gọi testrail_add_result_for_case để cập nhật status. Điều này xoá bỏ việc QA phải tick tay từng dòng sau mỗi lần chạy CI.

3. Báo cáo và tổng hợp. Agent đọc testrail_get_results_for_run rồi tự viết báo cáo dạng tóm tắt: bao nhiêu case pass/fail, case nào fail nhiều lần (flaky — không ổn định), coverage (độ phủ) theo module nào còn thiếu.

Tuy nhiên, có ranh giới rõ ràng cần giữ: AI không nên tự quyết định case nào "không cần test nữa" rồi archive hoặc xoá case mà không có review của con người. AI cũng không nên tự đóng (close) run khi vẫn còn case ở trạng thái "Untested" — đây là quyết định nghiệp vụ (business decision) cần QA lead xác nhận, không phải quyết định kỹ thuật thuần túy.

Mẹo: Luôn thêm ràng buộc trong system prompt hoặc trong file rule (ví dụ CLAUDE.md, .cursor/rules) rằng agent phải hỏi xác nhận trước khi gọi testrail_close_run hoặc bất kỳ tool có tính "phá hủy" (destructive) như xoá case. Coi các tool ghi dữ liệu như dao hai lưỡi: hữu ích khi có kiểm soát, nguy hiểm khi chạy tự động hoàn toàn (fully autonomous).

Giữ Đồng Bộ Dữ Liệu Giữa Test Thủ Công Và Test Tự Động

Một vấn đề kinh điển khi đưa AI vào workflow test: dữ liệu test manual (case do con người viết, chạy tay) và test automation (case chạy bởi CI/CD) dần dần lệch nhau. Case tự động có thể đã được refactor, đổi tên, tách nhỏ trong code, nhưng bên TestRail vẫn giữ case cũ — dẫn đến báo cáo coverage sai lệch nghiêm trọng.

Cách xử lý thực tế mà nhiều team áp dụng khi có AI hỗ trợ:

  • Gắn ID case TestRail vào code test tự động dưới dạng annotation hoặc comment, ví dụ // TestRail: C1024 trên đầu mỗi test function. Agent có thể đọc annotation này để map kết quả CI về đúng case, tránh tạo case trùng.
  • Định kỳ (ví dụ hàng tuần) yêu cầu agent quét cả 2 chiều: case nào trong TestRail có annotation trong code nhưng test đã bị xoá (case "mồ côi"), và ngược lại test nào trong code chưa có case tương ứng trong TestRail (case "vô danh").
  • Không để 2 nguồn tạo case độc lập. Nếu QA viết case thủ công và dev viết test automation riêng, không đồng bộ ID, sẽ dẫn đến 2 hệ thống đếm coverage khác nhau. Quy ước rõ: case TestRail luôn là nguồn sự thật (source of truth) về "cái gì cần test", còn code automation là "cái gì đã được tự động hoá" cho case đó.

Ví dụ prompt để agent giúp phát hiện lệch dữ liệu: "Đọc toàn bộ file test trong thư mục tests/e2e, trích các annotation TestRail: C-xxxx, so sánh với danh sách case trong suite 'Checkout' lấy từ testrail_get_cases, liệt kê case nào có annotation nhưng không tồn tại trong TestRail, và case nào tồn tại trong TestRail nhưng không có annotation nào trong code."

Mẹo: Đưa việc "audit đồng bộ TestRail-code" thành một task định kỳ chạy bởi agent (ví dụ mỗi sprint), không phải việc làm một lần rồi bỏ quên. Dữ liệu lệch dần theo thời gian, không phải lệch ngay lập tức — nên kiểm tra một lần đầu sẽ tạo cảm giác an toàn giả.

Mẹo

Trước khi đi sâu vào từng công cụ cụ thể ở các bài sau (Claude Code, Cursor, Gemini CLI, OpenCode), có vài nguyên tắc chung nên áp dụng ngay từ ngày đầu setup TestRail MCP:

  • Luôn bắt đầu với một project TestRail test (sandbox), không gắn trực tiếp vào project production ngay từ lần đầu chạy thử tool mới.
  • Ghi log mọi lệnh gọi tool có tính ghi dữ liệu (add/update/close) ra một file riêng trong vài tuần đầu, để dễ dàng review lại nếu có sự cố.
  • Thống nhất naming convention cho case (ví dụ tiền tố theo module: [Checkout] Áp dụng mã giảm giá hết hạn) và yêu cầu agent tuân thủ convention này trong mọi prompt tạo case, tránh tình trạng mỗi lần AI tạo case lại đặt tên theo văn phong khác nhau.

Mẹo: Lưu lại 3-5 prompt mẫu đã cho ra kết quả tốt (viết case, tạo run, tổng hợp báo cáo) thành một file dùng chung cho cả team, thay vì để mỗi người tự mò cách prompt. Đây chính là "runbook" prompt giúp chất lượng output của AI đồng nhất giữa các thành viên.

Tiếp TestRail MCP với Claude Code CLI and VS Code