Tiếng Việt: Puppeteer MCP With Gemini Cli

Nếu Claude Code là cái tên quen thuộc nhất khi nói về coding agent chạy trên terminal, thì Gemini CLI chính là câu trả lời mã nguồn mở (open-source) của Google cho cùng một bài toán. Điểm thú vị là Gemini CLI cũng hỗ trợ chuẩn MCP (Model Context Protocol — giao thức giúp AI agent gọi các công cụ/tool bên ngoài một cách chuẩn hoá), nghĩa là bạn hoàn toàn có thể gắn Puppeteer MCP server vào Gemini CLI và có một trợ lý AI biết "mở trình duyệt, click, chụp màn hình, đọc console log" y hệt như khi dùng với Claude Code.

Trong bài này, chúng ta sẽ đi từ việc cài đặt, kết nối Puppeteer MCP với Gemini CLI, cho đến việc dùng nó để tự động chẩn đoán lỗi frontend, chạy các luồng QA (quality assurance — kiểm thử chất lượng phần mềm), và cuối cùng là so sánh trải nghiệm thực tế giữa Gemini CLI và Claude Code khi cùng dùng Puppeteer MCP.

Installing and Connecting Puppeteer MCP to Gemini CLI

Trước tiên, bạn cần cài Gemini CLI nếu chưa có. Có hai cách phổ biến:

npx https://github.com/google-gemini/gemini-cli

npm install -g @google/gemini-cli

Sau khi cài xong, gõ gemini trong terminal để khởi động phiên làm việc đầu tiên. Gemini CLI sẽ yêu cầu bạn đăng nhập Google account (hoặc dùng API key riêng nếu bạn muốn dùng Gemini API trả phí thay vì gói miễn phí).

Cấu hình Puppeteer MCP server trong settings.json

Gemini CLI đọc cấu hình MCP server từ file ~/.gemini/settings.json (cấu trúc khá giống với mcpServers trong Claude Code, nên nếu bạn đã quen thuộc với Claude Code thì phần này gần như copy-paste được). Mở hoặc tạo file này:

mkdir -p ~/.gemini
nano ~/.gemini/settings.json

Thêm block mcpServers với Puppeteer MCP server (dùng package @modelcontextprotocol/server-puppeteer — server MCP chính thức do cộng đồng MCP maintain):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "trust": false
    }
  }
}

Vài lưu ý quan trọng khi cấu hình:

• command và args giống hệt cách bạn khai báo server này trong claude_desktop_config.json hay .mcp.json của Claude Code — vì bản chất MCP server không quan tâm client nào đang gọi nó.
• Trường trust là đặc thù của Gemini CLI. Nếu để false (mặc định), mỗi lần tool trong server này được gọi lần đầu (ví dụ puppeteer_navigate, puppeteer_click), Gemini CLI sẽ hiện prompt xác nhận (confirmation prompt) hỏi bạn có cho phép chạy không. Nếu set trust: true, toàn bộ tool của server này được tự động cho phép chạy mà không hỏi lại — tiện cho việc chạy tự động (automation) nhưng đánh đổi bằng việc mất một lớp kiểm soát an toàn.
• Nếu máy bạn chạy trong môi trường container/CI không có display, cân nhắc thêm biến môi trường PUPPETEER_LAUNCH_OPTIONS với "headless": true (chế độ không hiển thị cửa sổ trình duyệt) vào env của server config.

Kiểm tra kết nối

Sau khi lưu file, khởi động lại Gemini CLI (hoặc mở phiên mới), rồi gõ lệnh:

/mcp

Lệnh này trong Gemini CLI liệt kê toàn bộ MCP server đã cấu hình, trạng thái kết nối (connected/disconnected), và danh sách tool mà server đó expose ra (ví dụ puppeteer_navigate, puppeteer_screenshot, puppeteer_click, puppeteer_fill, puppeteer_evaluate...). Nếu bạn thấy dòng puppeteer — Ready kèm danh sách tool, nghĩa là kết nối thành công.

Ngoài ra, bạn có thể kiểm tra nhanh ngoài phiên chat bằng lệnh:

gemini mcp list

Lệnh này show toàn bộ MCP server đã đăng ký ở scope hiện tại (project-level hoặc user-level), tương tự claude mcp list bên Claude Code.

Về quyền hạn và tool confirmation

Gemini CLI có cơ chế "tool confirmation" khá chặt: mặc định, mọi tool call có khả năng thay đổi trạng thái (ví dụ điều hướng trang, click, gõ phím) đều bị chặn lại để hỏi người dùng xác nhận trước khi thực thi, trừ khi bạn đã đánh dấu "always allow" cho tool đó hoặc set trust: true cho cả server. Với Puppeteer — vốn có thể click vào nút "Xoá tài khoản" hay "Submit đơn hàng" trên trang thật — mình khuyên nên giữ trust: false khi mới làm quen, và chỉ bật trust: true khi bạn đã chạy thử nghiệm trên môi trường staging/local an toàn.

Mẹo: Nếu bạn thường xuyên test trên một trang staging nội bộ (không phải production), hãy tạo riêng một file .gemini/settings.json ở project-level (đặt tại thư mục gốc dự án thay vì ~/.gemini/) với trust: true, để không ảnh hưởng đến cấu hình an toàn mặc định ở các dự án khác.

Using Gemini CLI to Diagnose Frontend Issues Autonomously with Puppeteer MCP

Sức mạnh thực sự của việc gắn Puppeteer MCP vào một AI agent như Gemini CLI không nằm ở việc bạn phải ra lệnh từng bước ("click vào đây", "chụp ảnh màn hình đó"), mà nằm ở khả năng agent tự lên kế hoạch điều tra một cách autonomous (tự chủ): tự quyết định cần chụp ảnh gì, đọc log nào, thử tương tác nào để xác định nguyên nhân gốc rễ (root cause) của lỗi.

Ví dụ tình huống thực tế: một tester báo rằng nút "Thêm vào giỏ hàng" (Add to Cart) trên trang sản phẩm không phản hồi khi bấm, và giao diện bị vỡ layout khi xem trên mobile viewport. Thay vì tự mình debug, bạn có thể đưa cho Gemini CLI một prompt chi tiết như sau:

Tôi cần bạn điều tra 2 vấn đề trên trang https://staging.myshop.dev/products/wireless-earbuds-x200
bằng Puppeteer MCP:

1. Nút "Add to Cart" không phản hồi khi click.
2. Layout bị vỡ khi xem ở mobile viewport (375x667, giống iPhone SE).

Hãy thực hiện các bước sau và tổng hợp kết quả cuối cùng thành báo cáo:
- Điều hướng đến URL trên bằng viewport desktop (1440x900) trước, chụp screenshot toàn trang.
- Mở DevTools console log và network log ngay từ lúc trang bắt đầu load, ghi lại mọi
  console error, warning, và các request trả về status >= 400.
- Inspect DOM của nút "Add to Cart": lấy selector, kiểm tra xem nó có bị disabled,
  bị che phủ bởi overlay/z-index nào khác, hoặc có event listener nào gắn vào không
  (dùng puppeteer_evaluate để chạy getEventListeners hoặc kiểm tra thuộc tính onclick).
- Thử click vào nút đó và quan sát: có network request nào được gửi đi không, có
  console error nào xuất hiện ngay sau click không, DOM có thay đổi (ví dụ class
  "loading" được thêm vào) hay hoàn toàn im lặng.
- Sau đó đổi viewport sang 375x667 (mobile), chụp lại screenshot toàn trang và
  screenshot riêng phần header + nút Add to Cart.
- So sánh 2 screenshot desktop/mobile, chỉ ra cụ thể phần tử nào bị tràn (overflow),
  bị chồng lấp (overlap), hoặc bị ẩn ngoài viewport.

Cuối cùng, đưa ra giả thuyết nguyên nhân gốc rễ cho từng vấn đề (ví dụ: event listener
bị lỗi JS chặn ở dòng nào, CSS class nào gây vỡ layout mobile), kèm mức độ tin cậy
(confidence) cho mỗi giả thuyết, và đề xuất hướng fix.

Với prompt này, Gemini CLI sẽ tự gọi tuần tự các tool MCP tương ứng: puppeteer_navigate, puppeteer_screenshot, puppeteer_evaluate (để đọc DOM, console, hoặc chạy JavaScript kiểm tra event listener), và có thể gọi lại puppeteer_screenshot sau khi resize viewport. Điểm mạnh của Gemini là khả năng multimodal reasoning (suy luận trên cả dữ liệu hình ảnh lẫn văn bản) khá tốt — nó có thể "nhìn" vào screenshot và mô tả chính xác phần tử nào bị lệch, dù đôi khi cách diễn giải chi tiết pixel-level không sắc bén bằng việc đọc trực tiếp CSS computed style.

Một thực tế cần lưu ý: Gemini CLI đôi khi rút ngắn số bước điều tra nếu prompt không đủ chi tiết — ví dụ nó có thể chỉ chụp 1 screenshot rồi kết luận ngay thay vì đọc network log. Vì vậy, việc viết prompt tường minh từng bước như trên (thay vì chỉ nói "hãy debug giúp tôi cái nút này") sẽ giúp kết quả đáng tin cậy hơn nhiều.

Mẹo: Khi nghi ngờ lỗi liên quan đến JavaScript event binding, hãy yêu cầu Gemini CLI dùng puppeteer_evaluate để chạy đoạn script kiểm tra document.querySelector(...).outerHTML và so sánh với DOM mong đợi — nhiều trường hợp nút "không phản hồi" thực chất là do một lớp overlay vô hình (transparent div) đè lên trên, chứ không phải do JS lỗi.

Automating QA Flows and UI Exploration from Gemini CLI

Ngoài debug lỗi cụ thể, Puppeteer MCP kết hợp với Gemini CLI còn cực kỳ hữu ích cho việc chạy các luồng QA tự động — đặc biệt là khám phá các edge case (trường hợp biên) mà kịch bản test viết sẵn (scripted test) thường bỏ sót, vì agent có thể tự "thử" nhiều biến thể input khác nhau như một tester thực thụ.

Ví dụ, với một form đăng ký tài khoản, bạn có thể yêu cầu:

Hãy kiểm thử form đăng ký tại https://staging.myshop.dev/register bằng Puppeteer MCP.

Thực hiện các kịch bản sau, mỗi kịch bản chụp screenshot trước và sau khi submit:

1. Happy path: điền đầy đủ thông tin hợp lệ (email dạng test+{timestamp}@example.com,
   password đủ 8 ký tự có chữ hoa/thường/số, xác nhận password khớp), submit và xác
   nhận có redirect đến trang /welcome hay không.
2. Edge case: để trống trường email, submit, kiểm tra thông báo lỗi có hiển thị đúng
   vị trí và đúng nội dung không.
3. Edge case: nhập password và confirm password không khớp nhau, kiểm tra validation
   client-side có chặn submit trước khi gọi API không.
4. Edge case: nhập email đã tồn tại trong hệ thống (dùng admin@myshop.dev), kiểm tra
   response từ network log trả về status code gì và message hiển thị cho user.
5. Edge case: nhập password rất dài (300 ký tự) và email chứa ký tự Unicode
   (ví dụ "tester+việt@example.com"), xem form có bị crash hay validation sai không.

Sau mỗi kịch bản, ghi lại: DOM state của thông báo lỗi (nếu có), status code của
network request, và bất kỳ console error nào xuất hiện. Tổng hợp thành bảng kết quả
pass/fail cho từng kịch bản.

Bảng dưới đây liệt kê các tool call phổ biến của Puppeteer MCP mà bạn sẽ thấy Gemini CLI gọi trong các luồng QA dạng này:

Với việc khám phá trạng thái ứng dụng (UI exploration), bạn cũng có thể ra lệnh kiểu "khám phá tự do" thay vì kịch bản cứng:

Hãy khám phá toàn bộ luồng checkout của https://staging.myshop.dev, từ giỏ hàng đến
trang xác nhận đơn hàng. Ghi lại tất cả trạng thái (state) khác nhau mà bạn gặp:
loading state, empty cart state, trạng thái áp mã giảm giá không hợp lệ, trạng thái
hết hàng (out of stock). Với mỗi trạng thái, chụp screenshot và mô tả ngắn gọn UX
có vấn đề gì không (ví dụ: nút bị disable nhưng không có visual feedback, thông báo
lỗi biến mất quá nhanh).

Cách tiếp cận "khám phá tự do" này tận dụng đúng thế mạnh của agentic AI (AI mang tính agentic — biết tự lập kế hoạch và ra quyết định) thay vì chỉ chạy lại đúng những gì bạn đã liệt kê sẵn, giúp phát hiện những bug mà con người dễ bỏ sót vì đã quen với luồng "đúng" của ứng dụng.

Mẹo: Khi chạy các luồng QA có nhiều bước, hãy yêu cầu Gemini CLI xuất kết quả dưới dạng bảng markdown (pass/fail + ghi chú) ngay trong câu trả lời — việc này giúp bạn copy thẳng vào báo cáo test hoặc ticket Jira mà không cần định dạng lại thủ công.

Comparing Puppeteer MCP Frontend Debugging Output Between Gemini CLI and Claude Code

Cả Gemini CLI và Claude Code đều dùng chung một Puppeteer MCP server, gọi chung một bộ tool — nhưng trải nghiệm thực tế lại khác nhau khá rõ, vì phần "não" điều phối (orchestration) và mô hình nền tảng (underlying model) khác nhau. Dưới đây là bảng so sánh dựa trên quan sát thực tế khi chạy cùng một task debug/QA trên cả hai công cụ:

Vài quan sát đáng chú ý thêm:

• Context window lớn của Gemini thực sự là lợi thế khi bạn cần agent nhớ lại toàn bộ chuỗi 10-20 screenshot cộng với log console/network dài trong một phiên điều tra kéo dài — Claude Code có thể cần bạn tóm tắt lại hoặc mở phiên mới khi ngữ cảnh quá dài, dù các model Claude gần đây cũng đã có context window lớn hơn đáng kể so với trước.
• Claude Code có xu hướng "thận trọng" hơn khi đưa ra kết luận — nó thường nêu rõ mức độ tin cậy, và ít khi bịa ra kết luận khi thiếu dữ liệu (ví dụ nói "cần thêm log để xác nhận" thay vì đoán bừa).
• Gemini CLI phản hồi nhanh, phù hợp cho vòng lặp thử-sai (trial and error) nhanh khi bạn muốn liên tục thử nhiều biến thể prompt để tìm ra cách diễn đạt hiệu quả nhất.
• Không có công cụ nào "thắng tuyệt đối" — trong thực tế, nhiều team dùng cả hai: Gemini CLI cho các vòng khám phá nhanh, nhiều dữ liệu ngữ cảnh, và Claude Code cho các bước phân tích sâu, cần độ chính xác cao trước khi báo cáo bug chính thức.

Mẹo: Nếu ngân sách cho phép, hãy chạy song song cùng một prompt debug trên cả Gemini CLI và Claude Code cho các bug khó (flaky bug), rồi đối chiếu 2 bản kết luận — sự khác biệt trong cách 2 agent diễn giải cùng một screenshot thường tự nó đã là một gợi ý hữu ích về nguyên nhân thật sự của lỗi.