skills-ui-debug-agent
Skill inspect web/mobile applications bằng browser tools, phân tích DOM elements, xác định locators ổn định, debug UI automation failures, và hỗ trợ sinh Page Object classes.
anhtester · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add anhtester/claude-testing-kit --skill skills-ui-debug-agentAbout this skill
name: skills-ui-debug-agent description: Skill inspect web/mobile applications bằng browser tools, phân tích DOM elements, xác định locators ổn định, debug UI automation failures, và hỗ trợ sinh Page Object classes.
UI Debug Agent
Description
Skill chuyên biệt giúp agent inspect ứng dụng web/mobile trực tiếp trên browser thật, phân tích DOM, thu thập locators ổn định, và debug các vấn đề UI automation.
Agent có thể:
- Mở browser thật, navigate đến bất kỳ URL nào
- Inspect DOM elements — xác định attributes, hierarchy, state
- Thu thập locators ổn định cho Playwright, Selenium, Appium
- Debug automation failures (element not found, click intercepted, timeout)
- Capture UI state (snapshot, screenshot) để phân tích
- Phân tích dynamic content, iframe, shadow DOM, SPA navigation
When to Use
Sử dụng skill này khi:
- Cần khám phá UI của một trang web/module mới
- Cần tìm locator cho element cụ thể
- Cần debug test automation fail do UI thay đổi
- Cần verify locator có hoạt động trên DOM thực tế không
- Cần phân tích DOM để hiểu cấu trúc UI (forms, tables, modals)
- Cần capture evidence (screenshot) cho test report
Trigger keywords: "inspect UI", "tìm locator", "debug element", "mở browser xem", "kiểm tra DOM"
MCP Command Sequence (BẮT BUỘC)
Khi sử dụng Playwright MCP để debug UI, LUÔN tuân theo thứ tự:
1. browser_navigate(url) → Mở trang
2. browser_resize(1920, 1080) → Desktop viewport
3. browser_wait_for(text/time) → Chờ page load
4. browser_snapshot() → Thu thập DOM (dùng để phân tích + tìm locator)
5. browser_click/type/hover(ref) → Tương tác (nếu cần)
6. browser_take_screenshot() → Chụp ảnh (evidence khi fail hoặc milestone)
Quy tắc quan trọng:
| Quy tắc | Chi tiết |
|---|---|
| KHÔNG navigate lại nếu đã ở đúng trang | Tránh reload ngoài ý muốn |
| LUÔN resize ngay sau navigate | browser_resize(1920, 1080) — đảm bảo desktop viewport |
| LUÔN wait trước khi snapshot | Chờ page load hoàn tất |
| Dùng snapshot để phân tích | Snapshot trả về accessibility tree — nhanh, chính xác, có ref để tương tác |
| Dùng screenshot để báo cáo | Screenshot là hình ảnh — dùng khi cần evidence visual |
Snapshot vs Screenshot
browser_snapshot | browser_take_screenshot | |
|---|---|---|
| Trả về | Accessibility tree (text + ref IDs) | Hình ảnh (PNG/JPEG) |
| Mục đích | Phân tích DOM, tìm locator, xác định element | Visual evidence, báo cáo, debug layout |
| Khi nào dùng | ⭐ Luôn dùng trước khi tương tác | Chỉ khi fail hoặc milestone quan trọng |
| Có ref để interact | ✅ Có — dùng ref để click/type/hover | ❌ Không — chỉ là hình ảnh |
| Tốc độ | Nhanh | Chậm hơn |
Quy tắc: Ưu tiên snapshot cho phân tích, dùng screenshot cho evidence.
Quy trình Inspect UI
1. Mở & Chuẩn bị trang
browser_navigate → URL target
browser_resize → 1920 × 1080
browser_wait_for → chờ indicator page đã load (text hoặc thời gian)
Nếu trang yêu cầu đăng nhập:
- Hỏi user credentials HOẶC dùng fixture sẵn có trong project
- KHÔNG đọc file
.envtrực tiếp (quy tắc bảo mật)
2. Thu thập DOM Structure
browser_snapshot → accessibility tree
Từ snapshot, xác định:
- Các element chính: buttons, inputs, links, headings, tables
- Attributes quan trọng: role, name, label, placeholder, testid
- Hierarchy: parent → child relationships
- State: visible, enabled, disabled, checked, expanded
3. Xác định Locators
Với mỗi element cần locator, áp dụng priority order theo framework:
Playwright:
| Priority | Locator | Ví dụ | Khi nào dùng |
|---|---|---|---|
| 1 ⭐ | getByRole() | getByRole('button', {name: 'Submit'}) | Element có role + accessible name rõ ràng |
| 2 | getByLabel() | getByLabel('Email') | Form input có label |
| 3 | getByPlaceholder() | getByPlaceholder('Enter email') | Input có placeholder, không có label |
| 4 | getByText() | getByText('Welcome back') | Text content unique |
| 5 | getByTestId() | getByTestId('submit-btn') | Element có data-testid attribute |
| 6 | CSS | page.locator('.submit-button') | Không có semantic option nào phù hợp |
| 7 | XPath | page.locator('//div[@class="x"]') | Last resort — tránh dùng |
Selenium:
| Priority | Locator | Ví dụ |
|---|---|---|
| 1 ⭐ | By.id() | By.id("email") |
| 2 | By.cssSelector("[data-testid]") | By.cssSelector("[data-testid='submit']") |
| 3 | By.name() | By.name("username") |
| 4 | By.cssSelector() | By.cssSelector(".login-form button") |
| 5 | By.xpath() | By.xpath("//button[text()='Login']") |
Appium (Mobile):
| Priority | Locator | Ví dụ |
|---|---|---|
| 1 ⭐ | Accessibility ID | MobileBy.accessibilityId("loginButton") |
| 2 | ID (resource-id) | MobileBy.id("com.app:id/login_btn") |
| 3 | Name | MobileBy.name("Login") |
| 4 | XPath (relative) | MobileBy.xpath("//android.widget.Button[@text='Login']") |
4. Verify Locator
Sau khi xác định locator, bắt buộc verify trên DOM thực tế:
browser_snapshot → tìm element bằng ref
browser_click/type(ref) → thử tương tác
browser_snapshot → xác nhận kết quả
Locator được chấp nhận khi:
- Unique trên page (chỉ match 1 element)
- Ổn định qua nhiều lần reload
- Không chứa dynamic class (css-xxx, sc-xxx, MuiXxx-root)
- Không chứa positional xpath (//div[3]/button[2])
- Không phụ thuộc auto-generated attribute
Xử lý tình huống đặc biệt
Trang yêu cầu đăng nhập
- Dùng fixture login sẵn có trong project hoặc hỏi user credentials
- KHÔNG đọc .env trực tiếp
- Sau khi login, navigate đến trang cần inspect
Modal / Dialog / Popup
- Modal thường là overlay trên page chính
browser_snapshotsẽ thấy modal content trong accessibility tree- Tương tác với modal elements bằng ref từ snapshot
- Chờ modal animation hoàn thành trước khi interact
Iframe
browser_snapshotcó thể khô