·

TestRail MCP với OpenCode

Cài đặt TestRail MCP trong OpenCode để 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.

OpenCode là một agentic coding CLI mã nguồn mở, cho phép bạn tự chọn model backend (Claude, GPT, các model open-weight qua Ollama/OpenRouter...) và có hệ thống cấu hình MCP khá linh hoạt qua file opencode.json. Với team đã quen dùng OpenCode cho việc code, việc gắn thêm TestRail MCP server biến nó thành một trợ lý quản lý test toàn diện: từ quản lý suite, case, run, đến việc biến một user story thành cả một bộ test suite hoàn chỉnh. Bài này đi từ cách cài đặt, cách vận hành các thao tác quản lý hàng ngày, một ví dụ thực chiến chuyển đổi user story thành test suite, và những giới hạn cần biết khi dùng OpenCode cho việc này.

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

OpenCode đọc cấu hình MCP từ file opencode.json (đặt tại root project hoặc ở ~/.config/opencode/opencode.json cho cấu hình global). Khai báo TestRail MCP server như sau:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "testrail": {
      "type": "local",
      "command": ["npx", "-y", "mcp-server-testrail"],
      "environment": {
        "TESTRAIL_URL": "https://yourcompany.testrail.io",
        "TESTRAIL_EMAIL": "{env:TESTRAIL_EMAIL}",
        "TESTRAIL_API_KEY": "{env:TESTRAIL_API_KEY}",
        "TESTRAIL_PROJECT_ID": "12"
      },
      "enabled": true
    }
  }
}

Chạy opencode trong terminal, rồi gõ lệnh /mcp (hoặc kiểm tra qua status bar tuỳ version) để xác nhận server testrail đã kết nối. Nếu bạn dùng biến {env:TESTRAIL_API_KEY}, đảm bảo shell hiện tại đã export biến này (export TESTRAIL_API_KEY=... trong .zshrc/.bashrc, hoặc dùng direnv cho từng project) — OpenCode không tự đọc file .env như một số tool khác trừ khi bạn cấu hình thêm.

Một khác biệt đáng chú ý so với các client khác: OpenCode cho phép bật/tắt từng tool riêng lẻ trong permission config, ví dụ chỉ cho phép tool đọc (get_*) chạy tự động, còn tool ghi (add_*, update_*, close_*) phải hỏi xác nhận:

{
  "permission": {
    "mcp": {
      "testrail_get_*": "allow",
      "testrail_add_case": "ask",
      "testrail_update_case": "ask",
      "testrail_add_run": "ask",
      "testrail_close_run": "ask",
      "testrail_add_result_for_case": "ask"
    }
  }
}

Cấu hình này rất hữu ích cho workflow quản lý test: bạn để agent tự do đọc dữ liệu để trả lời câu hỏi, nhưng mọi hành động ghi đều cần bạn gõ "y" xác nhận ngay trong terminal trước khi thực thi.

Mẹo: Set permission mặc định là "ask" cho toàn bộ tool ghi trong ít nhất 2 tuần đầu sử dụng, dù bạn tin tưởng prompt của mình đến đâu. Việc quan sát agent xin phép trước mỗi hành động ghi giúp bạn hiểu rõ "logic" mà nó đang suy luận, từ đó viết prompt chính xác hơn về sau.

Quản Lý Suite, Case Và Run Từ OpenCode

Với TestRail MCP đã kết nối, các thao tác quản lý hàng ngày trở nên nhanh gọn hơn nhiều so với việc click chuột trên web UI. Vài ví dụ prompt thực tế cho công việc quản lý thường ngày:

Kiểm tra tổng quan suite:

Liệt kê tất cả suite trong project hiện tại, với mỗi suite cho biết số case,
số case chưa có run nào trong 30 ngày gần nhất (dựa vào testrail_get_runs
và testrail_get_results_for_run).

Dọn dẹp case trùng lặp:

Trong suite "Payment", tìm các case có title giống nhau trên 80% (dùng so sánh ngữ nghĩa,
không chỉ so khớp chuỗi), liệt kê thành cặp nghi trùng để tôi xem xét thủ công.
Không tự xoá case nào.

Tạo run theo milestone:

Tạo một run mới tên "Sprint 24 - Regression" trong suite "Payment",
bao gồm toàn bộ case có tag "regression", gắn với milestone "Release 3.2".

Điểm mạnh của OpenCode ở đây là khả năng kết hợp nhiều tool trong một chuỗi suy luận dài — ví dụ với yêu cầu dọn case trùng lặp, agent sẽ tự gọi testrail_get_cases, phân tích locally (không cần thêm tool riêng để so sánh chuỗi), rồi trả về danh sách nghi vấn dưới dạng bảng, không thực hiện hành động ghi nào cho đến khi bạn xác nhận từng cặp.

Mẹo: Với các yêu cầu "tìm và đề xuất" (không ghi dữ liệu), luôn thêm rõ câu "không tự xoá/sửa case nào" vào cuối prompt. Dù bạn đã set permission "ask" cho tool ghi, việc nói rõ ràng trong prompt giúp giảm số lần agent cố gắng "tiện tay" gọi luôn tool ghi ngay sau bước phân tích.

Ví Dụ Thực Chiến: Chuyển Đổi Một User Story Thành Bộ Test Suite Hoàn Chỉnh

Đây là ví dụ đầy đủ end-to-end mà bạn có thể áp dụng ngay. Giả sử bạn có user story:

"Là một khách hàng, tôi muốn lưu nhiều địa chỉ giao hàng để không phải nhập lại mỗi lần đặt hàng."

Prompt gửi cho OpenCode:

Đọc user story trong file docs/stories/saved-addresses.md.
Thực hiện các bước sau, in kết quả từng bước để tôi duyệt trước khi qua bước tiếp:

1. Phân tích user story, liệt kê các business rule ẩn (ví dụ: giới hạn số địa chỉ
   lưu tối đa, địa chỉ mặc định, validate định dạng địa chỉ).
2. Tạo Section mới "Saved Addresses" trong suite "Account Management".
3. Với mỗi business rule, tạo ít nhất 1 case happy path và 1 case edge case.
4. Tổng hợp: in ra bảng gồm tên case, priority, section, để tôi duyệt.
5. Sau khi tôi duyệt, gọi testrail_add_case cho các case đã chọn.

Cách chia prompt thành 5 bước rõ ràng, có điểm dừng để duyệt ở bước 4, là kỹ thuật quan trọng khi giao việc phức tạp cho agent — tránh tình trạng agent "nhảy cóc" thẳng đến hành động ghi dữ liệu trước khi bạn kịp xem qua logic phân tích của nó có hợp lý hay không.

Kết quả thực tế thường sẽ có các case như: "Lưu địa chỉ mới thành công", "Đặt địa chỉ mặc định", "Vượt quá số lượng địa chỉ tối đa cho phép (giả sử giới hạn 5)", "Địa chỉ với mã bưu điện không hợp lệ bị từ chối". Đây chính xác là loại phân rã (breakdown) mà QA senior thường làm thủ công — giờ agent làm nhanh gấp nhiều lần, miễn là business rule ẩn được liệt kê đúng ở bước 1.

Mẹo: Bước 1 (liệt kê business rule ẩn) là bước quan trọng nhất trong cả chuỗi, vì mọi case ở bước 3 phụ thuộc vào chất lượng của bước này. Nếu bạn thấy agent bỏ sót rule quan trọng, đừng sửa case ở bước 3 — hãy quay lại bổ sung ngữ cảnh ở bước 1 và chạy lại toàn bộ chuỗi.

Các Giới Hạn Đã Biết Của TestRail MCP Trong OpenCode

Không có công cụ nào hoàn hảo, và biết trước giới hạn giúp bạn tránh kỳ vọng sai:

  • Không hỗ trợ tốt custom field phức tạp. Nếu TestRail của bạn có custom field dạng dropdown với nhiều option lồng nhau hoặc field dạng multi-select, agent thường cần được cung cấp rõ danh sách option hợp lệ trong prompt, vì tool không tự "khám phá" được toàn bộ schema custom field một cách đáng tin cậy.
  • Không có tool xử lý attachment (file đính kèm) trong nhiều phiên bản mcp-server-testrail — nếu case cần đính kèm ảnh mockup hoặc file log, bạn vẫn phải upload thủ công qua web UI sau khi case được agent tạo.
  • Giới hạn ngữ cảnh khi suite quá lớn. Với suite có hàng nghìn case, gọi testrail_get_cases trả về toàn bộ có thể vượt context window (cửa sổ ngữ cảnh) của model. Nên luôn filter theo section hoặc theo tag khi làm việc với suite lớn, tránh yêu cầu "lấy toàn bộ case trong suite" một cách mù quáng.
  • Không có transaction/rollback. Nếu agent tạo 10 case và case thứ 7 lỗi (ví dụ do trùng field bắt buộc), 6 case trước đó vẫn đã được ghi vào TestRail — không có cơ chế tự động hoàn tác (rollback) toàn bộ batch.

Mẹo: Với batch tạo case lớn (trên 15-20 case), yêu cầu agent tạo theo từng nhóm nhỏ 5 case một lần, kèm log lại case ID vừa tạo. Nếu có lỗi giữa batch, bạn chỉ cần xử lý phần còn thiếu, không phải dò lại toàn bộ danh sách để biết cái nào đã được tạo thành công.

Mẹo

Kinh nghiệm thực tế khi vận hành TestRail MCP qua OpenCode trong một team nhiều người dùng chung:

  • Thống nhất một file opencode.json chuẩn commit vào repo, chỉ khác nhau ở biến môi trường cá nhân (API key riêng từng người), để mọi thành viên có cùng permission policy.
  • Với OpenCode, tận dụng khả năng chọn model khác nhau cho từng loại việc: dùng model mạnh (ví dụ Claude Opus) cho bước phân tích business rule phức tạp, dùng model nhẹ hơn cho các thao tác đơn giản như liệt kê case — tối ưu chi phí mà không giảm chất lượng ở bước quan trọng.
  • Backup định kỳ (export) dữ liệu case quan trọng ra file markdown/CSV song song với TestRail, đặc biệt trong giai đoạn đầu thử nghiệm AI-generated case, để có điểm đối chiếu nếu cần rollback thủ công.

Mẹo: Nếu OpenCode báo lỗi timeout khi gọi tool TestRail (thường do network hoặc do TestRail instance đang chậm), đừng lập tức retry với đúng prompt cũ — trước tiên kiểm tra bằng testrail_get_projects (một tool đọc nhẹ) để xác nhận kết nối còn sống, tránh gửi lại một lệnh ghi dữ liệu nặng khi server chưa chắc đã phản hồi ổn định.

Tiếp TestRail MCP với Gemini CLI