Chuyển đến nội dung chính

Công cụ

Các công cụ sau đây có sẵn thông qua máy chủ WebdriverIO MCP. Những công cụ này cho phép trợ lý AI tự động hóa trình duyệt và ứng dụng di động.

Quản lý Phiên​

start_browser​

Khởi chạy một phiên trình duyệt Chrome.

Tham số​

Tham sốKiểuBắt buộcMặc địnhMô tả
headlessbooleanKhôngfalseChạy Chrome ở chế độ headless
windowWidthnumberKhông1920Chiều rộng cửa sổ trình duyệt (400-3840)
windowHeightnumberKhông1080Chiều cao cửa sổ trình duyệt (400-2160)
navigationUrlstringKhông-URL để điều hướng đến sau khi khởi động trình duyệt

Ví dụ​

Start a browser with 1920x1080 resolution and navigate to webdriver.io

Hỗ trợ​

  • Desktop Browsers

start_app_session​

Khởi chạy một phiên ứng dụng di động trên iOS hoặc Android thông qua Appium.

Tham số​

Tham sốKiểuBắt buộcMặc địnhMô tả
platformstringCó-Nền tảng để tự động hóa: iOS hoặc Android
deviceNamestringCó-Tên của thiết bị hoặc simulator/emulator
appPathstringKhông*-Đường dẫn đến tập tin ứng dụng (.app, .ipa, hoặc .apk)
platformVersionstringKhông-Phiên bản hệ điều hành (ví dụ: 17.0, 14)
automationNamestringKhôngAutoXCUITest (iOS), UiAutomator2 hoặc Espresso (Android)
udidstringKhông-Mã định danh thiết bị duy nhất (bắt buộc cho thiết bị iOS thực)
noResetbooleanKhôngfalseGiữ nguyên trạng thái ứng dụng giữa các phiên
fullResetbooleanKhôngtrueGỡ cài đặt và cài đặt lại ứng dụng trước phiên
autoGrantPermissionsbooleanKhôngtrueTự động cấp quyền cho ứng dụng
autoAcceptAlertsbooleanKhôngtrueTự động chấp nhận các thông báo hệ thống
autoDismissAlertsbooleanKhôngfalseTừ chối (thay vì chấp nhận) các thông báo
appWaitActivitystringKhông-Activity để đợi khi khởi động (chỉ Android)
newCommandTimeoutnumberKhông60Số giây trước khi phiên hết hạn do không hoạt động
appiumHoststringKhông127.0.0.1Hostname máy chủ Appium
appiumPortnumberKhông4723Cổng máy chủ Appium
appiumPathstringKhông/Đường dẫn máy chủ Appium

*Hoặc appPath phải được cung cấp, hoặc noReset: true để kết nối với ứng dụng đang chạy.

Ví dụ​

Start an iOS app session on iPhone 15 simulator with my app at /path/to/app.app

Hỗ trợ​

  • iOS Simulators
  • iOS Real Devices
  • Android Emulators
  • Android Real Devices

close_session​

Đóng phiên trình duyệt hoặc ứng dụng hiện tại.

Tham số​

Tham sốKiểuBắt buộcMặc địnhMô tả
detachbooleanKhôngfalseTách khỏi phiên thay vì đóng (giữ cho trình duyệt/ứng dụng tiếp tục chạy)

Ghi chú​

Các phiên với noReset: true hoặc không có appPath tự động tách khi đóng để bảo toàn trạng thái.

Hỗ trợ​

  • Desktop Browsers
  • Mobile Apps

Điều hướng​

Điều hướng đến một URL.

Tham số​

Tham sốKiểuBắt buộcMô tả
urlstringCóURL để điều hướng đến

Ví dụ​

Navigate to https://webdriver.io

Hỗ trợ​

  • Desktop Browsers

Tương tác Phần tử​

click_element​

Nhấp vào một phần tử được xác định bởi một bộ chọn.

Tham số​

Tham sốKiểuBắt buộcMặc địnhMô tả
selectorstringCó-Bộ chọn CSS, XPath, hoặc bộ chọn di động
scrollToViewbooleanKhôngtrueCuộn phần tử vào tầm nhìn trước khi nhấp
timeoutnumberKhông3000Thời gian tối đa để đợi phần tử (ms)

Ghi chú​

  • Hỗ trợ bộ chọn văn bản WebdriverIO: button=Exact text hoặc a*=Contains text
  • Sử dụng căn chỉnh trung tâm cho vị trí cuộn

Ví dụ​

Click the element with selector "#submit-button"

Hỗ trợ​

  • Desktop Browsers
  • Mobile Native Apps

set_value​

Nhập văn bản vào một trường nhập liệu.

Tham số​

Tham sốKiểuBắt buộcMặc địnhMô tả
selectorstringCó-Bộ chọn cho phần tử nhập liệu
valuestringCó-Văn bản để nhập
scrollToViewbooleanKhôngtrueCuộn phần tử vào tầm nhìn trước khi nhập
timeoutnumberKhông3000Thời gian tối đa để đợi phần tử (ms)

Ghi chú​

Xóa giá trị hiện có trước khi nhập văn bản mới.

Ví dụ​

Set the value "john@example.com" in the element with selector "#email"

Hỗ trợ​

  • Desktop Browsers
  • Mobile Native Apps

Phân tích Trang​

get_visible_elements​

Lấy các phần tử hiển thị và có thể tương tác trên trang hiện tại hoặc màn hình. Đây là công cụ chính để phát hiện những phần tử có sẵn để tương tác.

Tham số​

Tham sốKiểuBắt buộcMặc địnhMô tả
elementTypestringKhônginteractableLoại phần tử: interactable (nút/liên kết/nhập liệu), visual (hình ảnh/SVG), hoặc all
inViewportOnlybooleanKhôngtrueChỉ trả về các phần tử hiển thị trong khung nhìn
includeContainersbooleanKhôngfalseBao gồm các container bố cục (ViewGroup, ScrollView, v.v.)
includeBoundsbooleanKhôngfalseBao gồm tọa độ phần tử (x, y, width, height)
limitnumberKhông0Số phần tử tối đa để trả về (0 = không giới hạn)
offsetnumberKhông0Số phần tử để bỏ qua (để phân trang)

Trả về​

{
  "total": 42,
  "showing": 20,
  "hasMore": true,
  "elements": [...]
}

Các phần tử Web bao gồm: tagName, type, id, className, textContent, value, placeholder, href, ariaLabel, role, cssSelector, isInViewport

Các phần tử Di động bao gồm: Nhiều chiến lược định vị (accessibility ID, resource ID, XPath, UiAutomator/predicates), loại phần tử, văn bản, và tùy chọn giới hạn

Ghi chú​

  • Web: Sử dụng script trình duyệt được tối ưu hóa để phát hiện phần tử nhanh
  • Di động: Sử dụng phân tích nguồn trang XML hiệu quả (2 HTTP calls thay vì 600+ cho các truy vấn phần tử)
  • Sử dụng phân trang (limit và offset) cho các trang lớn để giảm sử dụng token

Ví dụ​

Get all visible elements on the page with their coordinates

Hỗ trợ​

  • Desktop Browsers
  • Mobile Apps

get_accessibility​

Lấy cây trợ năng của trang hiện tại với thông tin ngữ nghĩa về vai trò, tên và trạng thái.

Tham số​

Tham sốKiểuBắt buộcMặc địnhMô tả
limitnumberKhông100Số nút tối đa để trả về (0 = không giới hạn)
offsetnumberKhông0Số nút để bỏ qua (để phân trang)
rolesstring[]KhôngAllLọc theo vai trò cụ thể (ví dụ: ["button", "link", "textbox"])
namedOnlybooleanKhôngtrueChỉ trả về các nút có tên/nhãn

Trả về​

{
  "total": 85,
  "showing": 100,
  "hasMore": false,
  "nodes": [
    { "role": "button", "name": "Submit" },
    { "role": "link", "name": "Home" }
  ]
}

Ghi chú​

  • Chỉ dành cho trình duyệt. Đối với ứng dụng di động, sử dụng get_visible_elements thay thế
  • Hữu ích khi get_visible_elements không trả về các phần tử mong đợi
  • namedOnly: true lọc ra các container ẩn danh và giảm nhiễu

Hỗ trợ​

  • Desktop Browsers

Chụp màn hình​

take_screenshot​

Chụp ảnh màn hình của khung nhìn hiện tại.

Tham số​

Tham sốKiểuBắt buộcMô tả
outputPathstringKhôngĐường dẫn để lưu tệp ảnh chụp màn hình. Nếu bỏ qua, trả về dữ liệu base64

Trả về​

Dữ liệu hình ảnh mã hóa base64 (PNG hoặc JPEG) với thông tin kích thước.

Ghi chú​

Ảnh chụp màn hình được tối ưu hóa tự động:

  • Kích thước tối đa: 2000px (được thu nhỏ nếu lớn hơn)
  • Kích thước tệp tối đa: 1MB
  • Định dạng: PNG với nén tối đa, hoặc JPEG nếu cần để đáp ứng giới hạn kích thước

Hỗ trợ​

  • Desktop Browsers
  • Mobile Apps

Cuộn trang​

scroll​

Cuộn trang lên hoặc xuống một số pixel nhất định.

Tham số​

Tham sốKiểuBắt buộcMặc địnhMô tả
directionstringCó-Hướng cuộn: up hoặc down
pixelsnumberKhông500Số pixel để cuộn

Ghi chú​

Chỉ dành cho trình duyệt. Đối với cuộn di động, sử dụng công cụ swipe thay thế.

Hỗ trợ​

  • Desktop Browsers

get_cookies​

Lấy cookie từ phiên hiện tại.

Tham số​

Tham sốKiểuBắt buộcMô tả
namestringKhôngTên cookie cụ thể để lấy (bỏ qua để lấy tất cả cookie)

Trả về​

Các đối tượng cookie với name, value, domain, path, expiry, secure và httpOnly.

Hỗ trợ​

  • Desktop Browsers

Đặt cookie trong phiên hiện tại.

Tham số​

Tham sốKiểuBắt buộcMặc địnhMô tả
namestringCó-Tên cookie
valuestringCó-Giá trị cookie
domainstringKhôngHiện tạiDomain cookie
pathstringKhông/Đường dẫn cookie
expirynumberKhông-Thời hạn dưới dạng timestamp Unix (giây)
securebooleanKhông-Cờ bảo mật
httpOnlybooleanKhông-Cờ HttpOnly
sameSitestringKhông-Thuộc tính SameSite: strict, lax, hoặc none

Hỗ trợ​

  • Desktop Browsers

delete_cookies​

Xóa cookie khỏi phiên hiện tại.

Tham số​

Tham sốKiểuBắt buộcMô tả
namestringKhôngTên cookie cụ thể để xóa (bỏ qua để xóa tất cả)

Hỗ trợ​

  • Desktop Browsers

Cử chỉ Cảm ứng (Di động)​

tap_element​

Chạm vào một phần tử hoặc tọa độ màn hình.

Tham số​

Tham sốKiểuBắt buộcMô tả
selectorstringKhông*Bộ chọn cho phần tử để chạm
xnumberKhông*Tọa độ X để chạm
ynumberKhông*Tọa độ Y để chạm

*Hoặc selector hoặc cả x và y đều bắt buộc.

Hỗ trợ​

  • Mobile Apps

swipe​

Thực hiện cử chỉ vuốt theo hướng được chỉ định.

Tham số​

Tham sốKiểuBắt buộcMặc địnhMô tả
directionstringCó-Hướng vuốt: up, down, left, right
durationnumberKhông500Thời lượng vuốt tính bằng mili giây (100-5000)
percentnumberKhông0.5/0.95Phần trăm màn hình để vuốt (0-1)

Ghi chú​

  • Phần trăm mặc định: 0.5 cho vuốt dọc, 0.95 cho vuốt ngang
  • Hướng chỉ ra chuyển động nội dung: "vuốt lên" cuộn nội dung lên

Ví dụ​

Swipe up to scroll down the screen

Hỗ trợ​

  • Mobile Apps

drag_and_drop​

Kéo một phần tử đến phần tử khác hoặc đến tọa độ.

Tham số​

Tham sốKiểuBắt buộcMô tả
sourceSelectorstringCóBộ chọn phần tử nguồn để kéo
targetSelectorstringKhông*Bộ chọn phần tử đích để thả vào
xnumberKhông*Offset X đích (nếu không có targetSelector)
ynumberKhông*Offset Y đích (nếu không có targetSelector)
durationnumberKhôngMặc định

*Hoặc targetSelector hoặc cả x và y đều bắt buộc.

Hỗ trợ​

  • Mobile Apps

Vòng đời Ứng dụng (Di động)​

get_app_state​

Lấy trạng thái hiện tại của ứng dụng.

Tham số​

Tham sốKiểuBắt buộcMô tả
bundleIdstringCóĐịnh danh ứng dụng (bundle ID cho iOS, package name cho Android)

Trả về​

Trạng thái ứng dụng: not installed, not running, running in background (suspended), running in background, hoặc running in foreground.

Hỗ trợ​

  • Mobile Apps

Chuyển đổi Context (Ứng dụng Hybrid)​

get_contexts​

Liệt kê tất cả các context có sẵn (native và webview).

Tham số​

Không

Trả về​

Mảng tên context (ví dụ: ["NATIVE_APP", "WEBVIEW_com.example.app"]).

Hỗ trợ​

  • Mobile Hybrid Apps

get_current_context​

Lấy context đang hoạt động hiện tại.

Tham số​

Không

Trả về​

Tên context hiện tại (ví dụ: NATIVE_APP hoặc WEBVIEW_*).

Hỗ trợ​

  • Mobile Hybrid Apps

switch_context​

Chuyển đổi giữa các context native và webview.

Tham số​

Tham sốKiểuBắt buộcMô tả
contextstringCóTên context hoặc chỉ số (bắt đầu từ 1) từ get_contexts

Ví dụ​

Switch to the WEBVIEW_com.example.app context

Hỗ trợ​

  • Mobile Hybrid Apps

Điều khiển Thiết bị (Di động)​

rotate_device​

Xoay thiết bị theo hướng cụ thể.

Tham số​

Tham sốKiểuBắt buộcMô tả
orientationstringCóPORTRAIT hoặc LANDSCAPE

Hỗ trợ​

  • Mobile Apps

hide_keyboard​

Ẩn bàn phím trên màn hình.

Tham số​

Không

Hỗ trợ​

  • Mobile Apps

get_geolocation​

Lấy tọa độ GPS hiện tại.

Tham số​

Không

Trả về​

Đối tượng với latitude, longitude, và altitude.

Hỗ trợ​

  • Mobile Apps

set_geolocation​

Đặt tọa độ GPS của thiết bị.

Tham số​

Tham sốKiểuBắt buộcMô tả
latitudenumberCóTọa độ vĩ độ (-90 đến 90)
longitudenumberCóTọa độ kinh độ (-180 đến 180)
altitudenumberKhôngĐộ cao tính bằng mét

Ví dụ​

Set geolocation to San Francisco (37.7749, -122.4194)

Hỗ trợ​

  • Mobile Apps

Thực thi Script​

execute_script​

Thực thi JavaScript trong trình duyệt hoặc lệnh di động thông qua Appium.

Tham số​

Tham sốKiểuBắt buộcMô tả
scriptstringCóMã JavaScript (trình duyệt) hoặc lệnh di động (ví dụ: mobile: pressKey)
argsarrayKhôngCác đối số cho script

Ví dụ Trình duyệt​

// Get page title
execute_script({ script: "return document.title" })

// Get scroll position
execute_script({ script: "return window.scrollY" })

// Click element by selector
execute_script({ script: "arguments[0].click()", args: ["#myButton"] })

Ví dụ Di động (Appium)​

// Press back key (Android)
execute_script({ script: "mobile: pressKey", args: [{ keycode: 4 }] })

// Activate app
execute_script({ script: "mobile: activateApp", args: [{ appId: "com.example" }] })

// Terminate app
execute_script({ script: "mobile: terminateApp", args: [{ appId: "com.example" }] })

// Deep link
execute_script({ script: "mobile: deepLink", args: [{ url: "myapp://screen", package: "com.example" }] })

// Shell command (Android)
execute_script({ script: "mobile: shell", args: [{ command: "dumpsys", args: ["battery"] }] })

Mã phím Android thông dụng​

PhímMã
BACK4
HOME3
ENTER66
MENU82
SEARCH84

Thêm Lệnh Di động​

Để biết danh sách đầy đủ các lệnh di động Appium có sẵn, xem:

Hỗ trợ​

  • Desktop Browsers
  • Mobile Apps (thông qua lệnh di động Appium)

Welcome! How can I help?

WebdriverIO AI Copilot