·

TestRail MCP với Claude Code CLI and VS Code

Cài đặt TestRail MCP trong Claude Code CLI and VS Code để 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.

Claude Code là một trong những client MCP mạnh nhất hiện nay cho workflow QA, vì nó vừa chạy được ở terminal (CLI) vừa có extension tích hợp trực tiếp vào VS Code — nghĩa là bạn có thể vừa đọc code test, vừa gọi tool TestRail, trong cùng một cửa sổ, không phải chuyển qua chuyển lại giữa nhiều app. Bài này hướng dẫn cách cài TestRail MCP server vào Claude Code, cách viết prompt để agent sinh case chất lượng, cách tạo run và đẩy kết quả automation lên TestRail ngay từ terminal, và các pattern prompt giúp output luôn nhất quán về cấu trúc và tên gọi.

Cài Đặt Và Kết Nối TestRail MCP Với Claude Code

Claude Code hỗ trợ đăng ký MCP server qua lệnh claude mcp add hoặc bằng cách khai báo trực tiếp trong file cấu hình project (.mcp.json ở root repo, hoặc cấu hình global). Cách nhanh nhất để thử nghiệm là dùng CLI:

claude mcp add testrail \
  --env TESTRAIL_URL=https://yourcompany.testrail.io \
  --env TESTRAIL_EMAIL=qa-bot@yourcompany.com \
  --env TESTRAIL_API_KEY=your-api-key-here \
  --env TESTRAIL_PROJECT_ID=12 \
  -- npx -y mcp-server-testrail

Nếu bạn muốn cấu hình này được chia sẻ cho cả team qua git, hãy khai báo trong .mcp.json tại root repo (Claude Code tự động đọc file này khi mở project):

{
  "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"
      }
    }
  }
}

Lưu ý: không commit API key trực tiếp vào file .mcp.json. Dùng cú pháp biến môi trường ${TESTRAIL_API_KEY} để Claude Code lấy giá trị thật từ shell environment hoặc từ file .env local (đã được thêm vào .gitignore). Sau khi cấu hình xong, gõ /mcp trong Claude Code để xem danh sách server đang kết nối — nếu testrail hiện trạng thái "connected" kèm số lượng tool (thường 10-15 tool), bạn đã sẵn sàng.

Với VS Code, cách làm tương tự: mở Command Palette → "Claude Code: Configure MCP Servers", paste đúng JSON trên. Ưu điểm khi dùng qua VS Code extension là bạn có thể click trực tiếp vào một file test, hỏi Claude "case TestRail nào tương ứng với file này", và Claude sẽ tự đọc annotation trong file rồi gọi testrail_get_cases để tra cứu — mọi thứ diễn ra trong 1 side panel, không rời khỏi editor.

Mẹo: Chạy thử với TESTRAIL_PROJECT_ID chỉ vào một project sandbox trong 1-2 ngày đầu. Khi đã quen với cách agent phản hồi, mới đổi sang project thật. Việc đổi biến môi trường chỉ mất vài giây nhưng tránh được rủi ro tạo nhầm dữ liệu ở project chính.

Sinh Test Case Từ Requirement Và Acceptance Criteria

Claude Code làm tốt việc biến một đoạn requirement thô thành bộ case có cấu trúc, miễn là bạn cung cấp đủ ngữ cảnh (context) và chỉ định rõ suite đích. Ví dụ prompt thực tế:

Đọc file docs/requirements/checkout-discount.md.
Dựa vào acceptance criteria trong file này, tạo test case cho suite "Checkout"
(project_id=12) trong TestRail, theo các quy tắc:
- Mỗi case phải có Precondition, Steps (đánh số), Expected Result rõ ràng.
- Nhóm case theo Section tương ứng: "Áp dụng mã giảm giá", "Mã giảm giá hết hạn",
  "Mã giảm giá không hợp lệ".
- Priority = High cho case liên quan đến tính đúng số tiền, Medium cho các case còn lại.
- Trước khi gọi testrail_add_case, in ra bảng danh sách case dự kiến để tôi duyệt.

Điểm quan trọng ở prompt này: yêu cầu agent in ra bảng trước khi ghi dữ liệu thật. Đây là bước review-before-write (duyệt trước khi ghi) cực kỳ quan trọng — Claude Code có thể gọi hàng loạt testrail_add_case trong vài giây, và nếu có case sai logic (ví dụ steps mô tả sai hành vi), bạn sẽ phải dọn dẹp thủ công sau đó, mất thời gian hơn nhiều so với việc duyệt trước 30 giây.

Sau khi bạn duyệt (trả lời "OK, tạo case số 1, 3, 4, bỏ case số 2"), Claude sẽ gọi tuần tự testrail_add_case cho từng case được chọn, đúng section_id tương ứng.

Mẹo: Thêm cụm "in ra bảng dự kiến trước khi ghi" thành một phần cố định trong file CLAUDE.md ở root repo (mục Instructions cho agent), thay vì phải nhắc lại mỗi lần prompt. Điều này biến review-before-write thành hành vi mặc định của agent trong toàn bộ project, không phụ thuộc vào việc bạn có nhớ nhắc hay không.

Tạo Test Run Và Đẩy Kết Quả Automation Từ Terminal

Sau khi CI chạy xong bộ test tự động (ví dụ Playwright, Cypress, hoặc Jest), bạn có thể yêu cầu Claude Code đọc report và đồng bộ kết quả lên TestRail ngay từ terminal, không cần mở web TestRail:

Đọc file test-results/junit.xml (định dạng JUnit XML từ lần chạy CI mới nhất).
Với mỗi test case trong report có annotation dạng "TestRail: C<số>" trong tên test,
hãy tạo một run mới trong suite "Checkout" tên "Regression - build #482",
rồi ghi result cho từng case: status_id=1 (Passed) nếu test pass,
status_id=5 (Failed) nếu test fail, kèm comment là nội dung lỗi (error message) nếu có.

Claude Code sẽ thực hiện chuỗi: testrail_add_run với include_all=false và danh sách case_ids được trích từ report, sau đó lặp qua từng case gọi testrail_add_result_for_case. Với các test fail, agent tự đính kèm đoạn stack trace vào field comment của result — điều này giúp QA đọc lại lịch sử lỗi trực tiếp trong TestRail mà không cần quay lại CI log.

Một pattern hữu ích khác: chạy lệnh này ngay trong CI pipeline bằng non-interactive mode của Claude Code (claude -p "..."), để việc đồng bộ diễn ra tự động sau mỗi lần build, không cần con người bấm tay:

claude -p "Đọc test-results/junit.xml, tạo run 'Regression - build #${BUILD_NUMBER}'
trong suite Checkout, ghi result cho từng case theo annotation TestRail: C<số>." \
  --allowedTools "mcp__testrail__*"

Mẹo: Khi chạy ở CI (non-interactive), luôn giới hạn --allowedTools chỉ cho phép tool bắt đầu bằng mcp__testrail__, không cho agent có quyền chạy shell command tuỳ ý trong bước này. Tách biệt quyền hạn giữa "bước build/test" và "bước đồng bộ TestRail" giảm thiểu rủi ro nếu prompt injection (chèn lệnh độc hại) xảy ra từ nội dung report bị giả mạo.

Pattern Prompt Để Cấu Trúc Và Tên Case Luôn Nhất Quán

Vấn đề lớn nhất khi để AI viết case hàng loạt là mỗi lần chạy, agent có thể chọn văn phong khác nhau — lúc thì viết steps dạng đoạn văn, lúc thì viết dạng danh sách; lúc đặt tên case bắt đầu bằng động từ, lúc lại bắt đầu bằng danh từ. Cách khắc phục hiệu quả là định nghĩa template case chuẩn ngay trong file rule của project, và luôn tham chiếu đến template này trong prompt.

Ví dụ đoạn quy tắc đặt trong CLAUDE.md:

## Quy tắc viết TestRail case

- Tên case theo mẫu: "[Tên chức năng] - [Hành vi được test]"
  Ví dụ: "Checkout - Áp dụng mã giảm giá hợp lệ"
- Custom field "Steps" (dạng Steps riêng biệt, không viết chung 1 đoạn):
  mỗi step gồm cột Step và cột Expected Result.
- Priority: High = ảnh hưởng tiền/dữ liệu người dùng, Medium = UI/UX,
  Low = trường hợp hiếm gặp.
- Type: Functional / Regression / Edge Case (không dùng loại khác).

Khi prompt của bạn chỉ cần nói "tạo case theo đúng quy tắc trong CLAUDE.md", Claude Code sẽ tự đọc file này (nó luôn được load vào context mỗi khi mở project) và áp dụng nhất quán, dù là bạn hay đồng nghiệp khác đang prompt.

Mẹo: Sau mỗi lần agent tạo một loạt case, dùng chính agent để tự kiểm tra chất lượng: "Đọc lại các case vừa tạo trong section X, chỉ ra case nào vi phạm quy tắc naming hoặc thiếu Expected Result." Đây là kỹ thuật self-review (agent tự soát lại việc mình vừa làm) rất hiệu quả để bắt lỗi trước khi con người phải đọc lại toàn bộ.

Mẹo

Vài lưu ý tổng hợp khi vận hành TestRail MCP với Claude Code trong thời gian dài:

  • Định kỳ chạy lại /mcp để kiểm tra server còn kết nối ổn định, đặc biệt sau khi update version của mcp-server-testrail.
  • Nếu team có nhiều project TestRail, xem xét tạo nhiều entry MCP server (testrail-project-a, testrail-project-b) với TESTRAIL_PROJECT_ID khác nhau, thay vì dùng chung 1 server rồi luôn phải nói rõ project trong mọi prompt.
  • Theo dõi giới hạn rate limit của TestRail API (thường vài trăm request/phút) khi để agent xử lý hàng loạt case hoặc result — nếu gặp lỗi 429, thêm chỉ dẫn cho agent tự retry với backoff (giãn thời gian giữa các lần thử lại).

Mẹo: Ghi lại toàn bộ transcript của những phiên Claude Code tạo run/case quan trọng (ví dụ trước một release lớn) vào một thư mục log riêng. Nếu sau này có tranh cãi về "case này ai tạo, dựa trên yêu cầu nào", bạn có ngay bằng chứng thay vì phải nhớ lại.

Tiếp TestRail MCP với OpenCode