Skip to main content

Tools

The WebdriverIO MCP server exposes 42 tools organized by function. Which of them your client sees depends on the active session and on the groups you enable, so read Tool visibility before relying on a tool being listed. Each section states any platform or group restriction that applies to its tools.

Every tool except start_session, attach_session, launch_chrome, list_apps, upload_app, query_docs and enable_tools also takes an optional session argument. It names a live session, either by the name it was started with or by its session ID, and you can omit it to use the default session. When you pass session, or when more than one session is live, the result starts with a line such as [session: admin (1a2b3c4d)] so you can tell which session answered. The sessionless tools do not take session, because they either create a session or do not use one.

Tool visibilityโ€‹

Every tool definition is sent with every model request, so the server hides tools that cannot apply yet. Three things decide what is listed.

Platform. Some tools work only on certain platforms. They are listed only while a session of a matching platform is active. With no session active, the browser set applies. The gated tools are:

PlatformTools
browserselect_option, press_key
electronexecute_electron_script, trigger_electron_deeplink, get_accessibility_tree, get_elements
ios, androidtap_element, swipe, drag_and_drop, switch_context, get_contexts, rotate_device, hide_keyboard, get_app_state, get_elements

Every other tool is listed on all platforms. get_elements is not listed on browser sessions, so read the wdio://session/current/elements resource there instead. Calling a tool that does not apply to the active session returns an error rather than running.

Groups. Tools that agents rarely need are hidden until their group is enabled with enable_tools. A group's tools still have to match the current platform to appear.

GroupToolsCovers
mocksmock, get_mock_calls, manage_mockMock network requests or Electron APIs
cookiesget_cookies, set_cookie, delete_cookiesRead, set and delete cookies
deviceemulate_device, set_geolocationEmulate a phone or tablet, fake the location
extensionsopen_web_extensionInstall and open a browser extension
attachlaunch_chrome, attach_sessionLaunch Chrome with remote debugging, attach to a running WebDriver or Appium session
elementsget_elementsRaw element list with bounds
cloud-appslist_apps, upload_appUpload and list mobile apps on BrowserStack, Sauce Labs, TestMu, TestingBot and Digital.ai

Everything up front. Some clients ignore tool list change notifications. For those, set WDIO_MCP_TOOLS=all in the server environment. Every tool is then listed from the start, and the platform and group rules above no longer hide anything. In this mode enable_tools is not registered at all, so the server exposes 41 tools instead of 42. Calls to a tool that does not apply to the active session still return an error.

enable_toolsโ€‹

Adds the tools of one or more groups to the list. The enabled groups stay enabled for the rest of the server process, and the tools appear right away in clients that honor tool list changes. Read-only and sessionless.

ParameterTypeRequiredDescription
groupsarray of "mocks" | "cookies" | "device" | "extensions" | "attach" | "elements" | "cloud-apps"โœ“Groups to enable. Pass at least one.

The result names the tools that were added. If none of the tools in the requested groups apply to the current session, it says so instead, for example when you enable elements on a browser session.

// Mocks and cookies, for a browser session
enable_tools({ groups: ["mocks", "cookies"] })

Session Managementโ€‹

start_sessionโ€‹

Starts a browser, Electron app or mobile app session. By default it closes the active session first. With onExisting: "keep" the new session runs alongside the sessions already live, and you target it by name through the session argument. Browsers run headless at 1280ร—800 by default; pass navigationUrl to open a page right away.

ParameterTypeRequiredDefaultDescription
namestringโ€”โ€”Name for this session, unique among live sessions. Target it from other tools with session: <name>
onExisting"close" | "keep"โ€”"close"close replaces the active session. keep runs the new session alongside the existing ones and does not make it the default
platform"browser" | "electron" | "ios" | "android"โœ“โ€”Session platform
provider"local" | "browserstack" | "saucelabs" | "testmu" | "testingbot" | "digitalai" | "external"โ€”"local"Session provider. Cloud providers read credentials from the environment. external connects to a W3C WebDriver endpoint set with webdriverConfig
browser"chrome" | "firefox" | "edge" | "safari"browser onlyโ€”Browser to launch
browserVersionstringโ€”โ€”Browser version on cloud providers; Electron version on electron sessions
osstringโ€”โ€”Operating system (cloud providers only). Provider-native; see Cloud Providers
osVersionstringโ€”โ€”OS version (cloud providers only). Provider-native; see Cloud Providers
headlessbooleanโ€”trueRun browser headlessly
windowWidthnumberโ€”1280Browser window width (400โ€“3840)
windowHeightnumberโ€”800Browser window height (400โ€“2160)
navigationUrlstringโ€”โ€”URL to open after starting
electronRootDirstringconditionalโ€”Project root of the Electron app, used to find Electron Builder or Forge configuration. Electron sessions need this or capabilities["wdio:electronServiceOptions"].appBinaryPath / .appEntryPoint
electronDeeplinkSchemestringโ€”โ€”URI scheme without the colon, such as "myapp". Required before trigger_electron_deeplink can run. Stored in lowercase
deviceNamestringmobile onlyโ€”Device, emulator or simulator name
deviceQuerystringโ€”โ€”Digital.ai mobile device query
platformVersionstringโ€”โ€”Mobile OS version (e.g. "17.0", "14")
appPathstringโ€”โ€”Local .app, .apk or .ipa to install
appstringโ€”โ€”Cloud app URL from upload_app: bs://โ€ฆ (BrowserStack), storage:filename=โ€ฆ (Sauce Labs), lt://โ€ฆ (TestMu), tb://โ€ฆ (TestingBot), or cloud:<name> (Digital.ai)
automationName"XCUITest" | "UiAutomator2"โ€”โ€”Automation driver (mobile only)
autoGrantPermissionsbooleanโ€”trueAuto-grant app permissions (mobile only)
autoAcceptAlertsbooleanโ€”trueAuto-accept alerts (mobile only)
autoDismissAlertsbooleanโ€”โ€”Auto-dismiss alerts (mobile only)
appWaitActivitystringโ€”โ€”Android activity to wait for on launch
udidstringโ€”โ€”iOS real device UDID
noResetbooleanโ€”โ€”Preserve app data between sessions
fullResetbooleanโ€”โ€”Uninstall app before and after the session
newCommandTimeoutnumberโ€”300Appium command timeout (seconds)
attachbooleanโ€”falseAttach to a running Chrome over CDP, using attachConfig. Run launch_chrome first
attachConfigobjectโ€”{ port: 9222, host: "localhost" }CDP connection. Missing keys fall back to these defaults
webdriverConfigobjectexternal only{ protocol: "http", hostname: "127.0.0.1", port: 4445, path: "/" }W3C WebDriver endpoint for provider: "external". Missing keys fall back to these defaults
appiumConfigobjectโ€”โ€”Local Appium server: { host, port, path, protocol }
tunnelboolean | "external"โ€”falseCloud providers. true starts a tunnel, "external" uses one that is already running
tunnelNamestringโ€”โ€”Tunnel identifier name
reportingobjectโ€”โ€”Cloud provider reporting labels: { project, build, session }
tracebooleanโ€”falseSave a Playwright-compatible trace zip to .trace/ on close_session
networkLogs"none" | "failures" | "all"โ€”"none"Local Chromium performance log capture. The default comes from WDIO_MCP_NETWORK_LOGS when set
region"us-west-1" | "eu-central-1" | "apac-southeast-1"โ€”"eu-central-1"Sauce Labs data center region
capabilitiesobjectโ€”โ€”Additional raw capabilities to merge, e.g. "wdio:electronServiceOptions"
// Local Chrome browser
start_session({ platform: "browser", browser: "chrome" })

// A named browser session that runs alongside the active one
start_session({ platform: "browser", browser: "chrome", name: "admin", onExisting: "keep" })

// Browser session with WebDriver BiDi, needed for mocks, emulate_device and open_web_extension
start_session({ platform: "browser", browser: "chrome", capabilities: { webSocketUrl: true } })

// Electron app, with a deeplink scheme for trigger_electron_deeplink
start_session({ platform: "electron", electronRootDir: "/path/to/app", electronDeeplinkScheme: "myapp" })

// iOS simulator
start_session({ platform: "ios", deviceName: "iPhone 16", platformVersion: "18.0", appPath: "/path/to/app.app" })

// BrowserStack Android
start_session({ platform: "android", provider: "browserstack", deviceName: "Samsung Galaxy S24", app: "bs://abc123" })

// Sauce Labs iOS
start_session({ platform: "ios", provider: "saucelabs", deviceName: "iPhone 15", platformVersion: "17.0", app: "storage:filename=MyApp.ipa" })

// TestMu browser
start_session({ platform: "browser", provider: "testmu", browser: "chrome", os: "Windows", osVersion: "11" })

// TestingBot browser
start_session({ platform: "browser", provider: "testingbot", browser: "chrome", os: "Windows", osVersion: "11" })

// Digital.ai Android
start_session({ platform: "android", provider: "digitalai", app: "cloud:<name>" })

// Cloud provider with tunnel
start_session({ platform: "browser", provider: "browserstack", browser: "chrome", tunnel: true })

// Attach to existing Chrome (after launch_chrome; the attach group must be enabled)
start_session({ platform: "browser", browser: "chrome", attach: true })

attach_sessionโ€‹

Attaches to an existing remote WebDriver or Appium session by ID, without creating a new session. It closes the active session unless you pass onExisting: "keep". Given only a name, with no sessionId, it looks up a session that is already live under that name. Names are scoped to this server process. An externally managed session is detached rather than terminated when it closes, by default. Sessionless and hidden until enable_tools({ groups: ["attach"] }). Electron sessions cannot be attached.

ParameterTypeRequiredDefaultDescription
sessionIdstringโ€”โ€”Existing remote WebDriver or Appium session ID. Required unless you only look up a live session by name
namestringโ€”โ€”Name to register the session under, or the name of a live session to look up when sessionId is omitted
onExisting"close" | "keep"โ€”"close"close replaces the active session. keep runs the attached session alongside the existing ones
provider"local" | "browserstack" | "saucelabs" | "testmu" | "testingbot" | "digitalai" | "external"โ€”"local"Provider hosting the existing session. Use "external" for a custom W3C WebDriver endpoint
platform"browser" | "ios" | "android"with sessionIdโ€”Platform of the existing session
browser"chrome" | "firefox" | "edge" | "safari"โ€”"chrome"Browser for local command registration (browser platform only)
automationName"XCUITest" | "UiAutomator2"โ€”โ€”Appium automation driver for local command registration (mobile only)
webdriverConfigobjectโ€”{ hostname: "127.0.0.1", port: 4445, path: "/", protocol: "http" }W3C WebDriver endpoint, with provider: "external"
appiumConfigobjectโ€”โ€”Appium server connection (local provider only): { host, port, path, protocol }
region"us-west-1" | "eu-central-1" | "apac-southeast-1"โ€”"eu-central-1"Sauce Labs region, with provider: "saucelabs"
tracebooleanโ€”falseRecord a trace for subsequent commands, saved to .trace/ on close_session
capabilitiesobjectโ€”โ€”Capabilities used to register the right browser or Appium command surface locally. They are not sent to the remote endpoint
// Attach to a session that is already running on a local Appium server
attach_session({ sessionId: "abc123", platform: "android", automationName: "UiAutomator2", name: "device" })

// Look up a session that is already live under a name
attach_session({ name: "device" })

close_sessionโ€‹

Closes or detaches from the current session.

ParameterTypeRequiredDefaultDescription
detachbooleanโ€”falseDisconnect without terminating (preserves app state on Appium)

Sessions started with noReset: true auto-detach by default.


launch_chromeโ€‹

Prepares a Chrome instance with remote debugging enabled so start_session({ attach: true }) can connect. Sessionless and hidden until enable_tools({ groups: ["attach"] }). Two modes:

  • newInstance (default): opens Chrome alongside your existing one using a separate profile directory; your current session is untouched.
  • freshSession: launches Chrome with an empty profile (no cookies, no logins). Use copyProfileFiles: true to carry over cookies and logins.
ParameterTypeRequiredDefaultDescription
portnumberโ€”9222Remote debugging port
mode"newInstance" | "freshSession"โ€”"newInstance"Launch mode
copyProfileFilesbooleanโ€”falseCopy Chrome Default profile (cookies, logins) into debug session

After this tool succeeds, call start_session({ platform: "browser", browser: "chrome", attach: true }).

Loads a URL in the current tab and waits for the page load event. Resets page state (DOM, JS runtime). Browser-only.

ParameterTypeRequiredDescription
urlstringโœ“URL to navigate to

get_tabsโ€‹

Lists all browser tabs with handle, title, URL, and which is active. Use before switch_tab to find the target handle. Browser-only.

No parameters.


switch_tabโ€‹

Focuses a browser tab by window handle or 0-based index. All subsequent tool calls operate on the newly active tab. Browser-only.

ParameterTypeRequiredDescription
handlestringโ€”Window handle to switch to
indexnumberโ€”0-based tab index (โ‰ฅ 0)

Provide either handle or index. Get handles from get_tabs or wdio://session/current/tabs.


switch_frameโ€‹

Switches WebDriver frame context into an iframe by CSS/XPath selector, or back to top-level if selector is omitted. Changes persist; all subsequent click_element, set_value, get_elements calls operate within the switched frame until you switch back. Waits up to 5s for the iframe. Browser-only.

ParameterTypeRequiredDescription
selectorstringโ€”CSS/XPath selector for the iframe element. Omit to switch back to the top-level frame.
// Switch into an iframe
switch_frame({ selector: "#my-iframe" })

// Interact with elements inside the iframe
click_element({ selector: "button.submit" })

// Switch back to top-level
switch_frame()

Element Interactionโ€‹

click_elementโ€‹

Clicks an element. On web pages the result lists what changed: new elements with refs, or the new page. In apps it does not, so take a snapshot to see the new screen. Several steps in a row belong in one perform_actions call.

ParameterTypeRequiredDefaultDescription
selectorstringโœ“โ€”Ref from snapshot (e.g. e12), or a CSS, XPath, button=Exact text or a*=Partial text selector

set_valueโ€‹

Replaces the text of an input or textarea. On web pages the result lists what changed. In apps it does not, so take a snapshot to see the new screen. To fill several fields, or fill and then click, use one perform_actions call.

ParameterTypeRequiredDefaultDescription
selectorstringโœ“โ€”Ref from snapshot (e.g. e12), or a CSS, XPath, button=Exact text or a*=Partial text selector
valuestringโœ“โ€”Text to enter into the element

select_optionโ€‹

Selects an option of a <select> by its text. The result lists what changed on the page. Browser-only.

ParameterTypeRequiredDescription
selectorstringโœ“Ref from snapshot (e.g. e12), or a selector of the <select>
valuestringโœ“Option text to select

press_keyโ€‹

Presses a key or combination in the focused element, such as Enter, Tab, Escape or Control+a. The result lists what changed on the page. Browser-only.

ParameterTypeRequiredDefaultDescription
keysstringโœ“โ€”Key or combination
timesnumberโ€”โ€”Press it this many times, e.g. to move a slider (1โ€“100)

perform_actionsโ€‹

Runs several actions in one call, such as filling a form and then submitting it, on the page or app screen. On web pages it returns what each step changed. Put every step of a sequence into one call rather than sending one tool call per step.

Each entry in actions names one of these action values: click, fill, select, check, uncheck or press. value is the text for fill, the option for select and the keys for press. times applies to press only.

The run stops at the first failure, when a step loads a new page, or before a key press that follows a click, select, check or uncheck that changed the page. Continue with the refs from the new result. Steps the current session does not support are rejected before any step runs.

ParameterTypeRequiredDefaultDescription
actionsobject[]โœ“โ€”Steps to run in order. At least one
actions[].actionstringโœ“โ€”"click" | "fill" | "select" | "check" | "uncheck" | "press"
actions[].selectorstringโ€”โ€”Ref (e.g. e12) or selector. Not used by press
actions[].valuestringโ€”โ€”Text for fill, option for select, keys for press
actions[].timesnumberโ€”โ€”press only: repeat count (1โ€“100)
perform_actions({ actions: [
{ action: "fill", selector: "e4", value: "ada@example.com" },
{ action: "fill", selector: "e5", value: "correct horse" },
{ action: "click", selector: "e6" },
] })

scrollโ€‹

Scrolls the page by a number of pixels. Browser-only. For mobile, use swipe.

ParameterTypeRequiredDefaultDescription
direction"up" | "down"โœ“โ€”Scroll direction
pixelsnumberโ€”500Pixels to scroll

Element Analysisโ€‹

snapshotโ€‹

Returns the page or app screen as an accessibility tree with refs, such as button "Save" [ref=e3]. This is the primary way to read a page: take a snapshot, then pass a ref such as e12 to click_element, set_value, select_option or perform_actions. Refs from the latest result stay valid until the page changes.

By default the snapshot lists interactive elements only and drops plain text. Pass full: true to include text. Pass find to return only the parts of the page that contain the text, with their refs. Pass viewport: true to limit the snapshot to what is on screen. find cannot be combined with viewport. Snapshots are capped at 12,000 characters, so use find or scope to narrow a large page.

ParameterTypeRequiredDefaultDescription
findstringโ€”โ€”Text to look for. Returns only the matching parts of the page, with refs
fullbooleanโ€”falseInclude text, not just interactive elements
scopestringโ€”โ€”Only the part below this ref or selector
viewportbooleanโ€”falseOnly what is on screen (not together with find)
// Read the page, then act on a ref from the result
snapshot()
click_element({ selector: "e12" })

// Find the part of the page that mentions a term
snapshot({ find: "Shipping address" })

get_elementsโ€‹

Returns interactable elements on the current page with selectors ready to use. Prefer the wdio://session/current/elements resource for ambient awareness; use this tool when you need filtering or pagination.

Platform: listed only on ios, android and electron sessions. It is not listed on browser sessions. Group: elements, so enable it with enable_tools({ groups: ["elements"] }) first.

ParameterTypeRequiredDefaultDescription
inViewportOnlybooleanโ€”falseOnly return viewport-visible elements
includeContainersbooleanโ€”falseInclude container elements (divs, sections)
includeBoundsbooleanโ€”falseInclude bounding box coordinates
limitnumberโ€”0Max elements to return (0 = unlimited)
offsetnumberโ€”0Elements to skip (pagination)

get_accessibility_treeโ€‹

Returns the accessibility tree with roles, names, and selectors. Supports filtering and pagination. Listed on Electron sessions: the platform gating in Tool visibility lists it only on electron sessions. It works in any web context, so with WDIO_MCP_TOOLS=all it also runs on browser sessions; it rejects native iOS and Android.

ParameterTypeRequiredDefaultDescription
limitnumberโ€”0Max nodes to return (0 = unlimited)
offsetnumberโ€”0Nodes to skip (pagination)
rolesstring[]โ€”โ€”Filter by ARIA roles, e.g. ["button", "link", "heading"]

Screenshotsโ€‹

get_screenshotโ€‹

Takes a screenshot of the current page or screen. Returns a base64-encoded image, automatically resized and compressed to stay within model context limits (max 1 MB, max 2000px).

No parameters. Prefer wdio://session/current/elements over screenshots for element discovery; it's faster and uses far fewer tokens. Use screenshots for visual verification or debugging layout.

Cookie tools are hidden until enable_tools({ groups: ["cookies"] }).

get_cookiesโ€‹

Returns all cookies for the current session, or a single cookie by name. Browser-only.

ParameterTypeRequiredDescription
namestringโ€”Cookie name. Omit to return all cookies.

Sets a browser cookie. The browser must already be on the target domain โ€” cookies cannot be set cross-domain. Use to inject session tokens or feature flags without going through login flows. Browser-only.

ParameterTypeRequiredDescription
namestringโœ“Cookie name
valuestringโœ“Cookie value
domainstringโ€”Cookie domain (defaults to current domain)
pathstringโ€”Cookie path (defaults to /)
expirynumberโ€”Expiry as Unix timestamp (seconds)
httpOnlybooleanโ€”HttpOnly flag
securebooleanโ€”Secure flag
sameSite"strict" | "lax" | "none"โ€”SameSite attribute

delete_cookiesโ€‹

Deletes all cookies or a specific cookie by name. Browser-only.

ParameterTypeRequiredDescription
namestringโ€”Cookie name to delete. Omit to delete all cookies.

Touch Gestures (Mobile)โ€‹

tap_elementโ€‹

Calls element.tap() on a matched element or taps at absolute screen coordinates. Use on iOS when click_element is ignored; tap is the native gesture iOS responds to. Mobile-only.

ParameterTypeRequiredDescription
selectorstringโ€”Element selector
xnumberโ€”X coordinate for screen tap (if no selector)
ynumberโ€”Y coordinate for screen tap (if no selector)

Provide either selector or x/y coordinates.


swipeโ€‹

Performs a full-screen swipe gesture. Direction is content movement direction (e.g. "up" scrolls a list upward). Use for scrolling beyond visible bounds. For moving a specific element, use drag_and_drop. Mobile-only. For browsers, use scroll.

ParameterTypeRequiredDefaultDescription
direction"up" | "down" | "left" | "right"โœ“โ€”Swipe direction
durationnumberโ€”500Swipe duration (ms, 100โ€“5000)
percentnumberโ€”0.5 / 0.95Fraction of screen to swipe (0โ€“1)

drag_and_dropโ€‹

Drags an element to another element or coordinates. Mobile-only.

ParameterTypeRequiredDefaultDescription
sourceSelectorstringโœ“โ€”Source element to drag
targetSelectorstringโ€”โ€”Target element to drop onto
xnumberโ€”โ€”Target X offset (if no targetSelector)
ynumberโ€”โ€”Target Y offset (if no targetSelector)
durationnumberโ€”โ€”Drag duration (ms, 100โ€“5000)

Context Switching (Mobile)โ€‹

get_contextsโ€‹

Returns available automation contexts and the currently active one. Use before switch_context to discover NATIVE_APP and WEBVIEW_* targets. Mobile-only.

No parameters.


switch_contextโ€‹

Switches between native and webview automation contexts in a hybrid mobile app. Required before using CSS/XPath selectors inside an embedded webview. Mobile-only.

ParameterTypeRequiredDescription
contextstringโœ“Context name, e.g. "NATIVE_APP", "WEBVIEW_com.example.app"

Get available context names from get_contexts or wdio://session/current/contexts.

// 1. Check what's available
get_contexts()
// โ†’ { contexts: ["NATIVE_APP", "WEBVIEW_com.example.app"], currentContext: "NATIVE_APP" }

// 2. Switch into the webview for CSS/XPath
switch_context({ context: "WEBVIEW_com.example.app" })

// 3. Interact with webview elements using CSS selectors
click_element({ selector: "#login-button" })

// 4. Switch back to native for native UI
switch_context({ context: "NATIVE_APP" })

Device Control (Mobile)โ€‹

rotate_deviceโ€‹

Rotates the device to portrait or landscape and waits for the OS rotation to complete. Use to test orientation-dependent layouts. Mobile-only.

ParameterTypeRequiredDescription
orientation"PORTRAIT" | "LANDSCAPE"โœ“Target orientation

hide_keyboardโ€‹

Dismisses the software keyboard. Call after text entry when the keyboard obscures elements you need next. No-op if already hidden. Mobile-only.

No parameters.


set_geolocationโ€‹

Overrides device GPS coordinates for the session. Affects navigator.geolocation on web and location services on mobile. Location permissions must be granted to the app beforehand. Hidden until enable_tools({ groups: ["device"] }).

ParameterTypeRequiredDescription
latitudenumberโœ“Latitude (โˆ’90 to 90)
longitudenumberโœ“Longitude (โˆ’180 to 180)
altitudenumberโ€”Altitude in metres

App Lifecycle (Mobile)โ€‹

get_app_stateโ€‹

Returns the current lifecycle state of a mobile app. Mobile-only.

ParameterTypeRequiredDescription
bundleIdstringโœ“iOS bundle ID or Android package name, e.g. "com.example.app"

Returns one of: not installed, not running, background (suspended), background, foreground.

Browser Utilitiesโ€‹

emulate_deviceโ€‹

Emulates a mobile or tablet device in the current browser session (sets viewport, DPR, user-agent, touch events). Requires a BiDi-enabled session: start_session({ capabilities: { webSocketUrl: true } }). Browser-only. Hidden until enable_tools({ groups: ["device"] }).

ParameterTypeRequiredDescription
devicestringโ€”Device preset name (e.g. "iPhone 15", "Pixel 7"). Omit to list presets. Pass "reset" to restore desktop defaults.

execute_scriptโ€‹

Executes JavaScript in the browser or mobile commands via Appium.

ParameterTypeRequiredDescription
scriptstringโœ“JS code (browser) or Appium command like "mobile: pressKey"
argsany[]โ€”Arguments passed to the script or command

Browser: use return to get values back.

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

// Scroll element into view
execute_script({ script: "arguments[0].scrollIntoView()", args: ["#my-element"] })

Mobile (Appium): uses mobile: <command> syntax.

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

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

// Deep link (iOS)
execute_script({ script: "mobile: deepLink", args: [{ url: "myapp://route", bundleId: "com.example.app" }] })

open_web_extensionโ€‹

Installs a web extension through WebDriver BiDi and opens one of its extension pages, so the other tools can inspect and drive its UI. Browser-only. Requires a BiDi-enabled session: start_session({ capabilities: { webSocketUrl: true } }). Hidden until enable_tools({ groups: ["extensions"] }).

Use the base64 form for cloud or remote sessions where the browser driver cannot read the MCP server's filesystem.

ParameterTypeRequiredDescription
extensionDataobjectโœ“One of { type: "path", path } (unpacked directory), { type: "archivePath", path } (packaged archive), or { type: "base64", value } (base64-encoded archive). Paths are on the remote end
pathstringโœ“Page inside the extension, such as options.html or popup.html. Leading slashes are ignored
// Install an unpacked extension and open its options page
open_web_extension({ extensionData: { type: "path", path: "/tmp/my-extension" }, path: "options.html" })

Electronโ€‹

Electron tools run only in Electron sessions, started with start_session({ platform: "electron" }). They are listed only while such a session is active.

execute_electron_scriptโ€‹

Executes JavaScript in the Electron main process, with access to the Electron APIs. This is privileged code execution, so use it only with trusted scripts. Electron-only.

ParameterTypeRequiredDescription
scriptstringโœ“JavaScript body. electron gives the Electron APIs, args the supplied values, and return sends back a result
argsany[]โ€”Values made available to the script as args[0], args[1], and so on
execute_electron_script({ script: "return electron.app.getName()" })

execute_electron_script({ script: "return args[0] + 1", args: [41] })

Triggers a deeplink through the running Electron app. The session must have been started with electronDeeplinkScheme, and the URL's scheme must match it. Packaged binaries are required for deeplinks on Windows and Linux. Electron-only.

ParameterTypeRequiredDescription
urlstringโœ“Deeplink URI, such as myapp://route/settings. Must be a valid URL with the session's scheme

Mockingโ€‹

Mocks are scoped to the session that created them. The three mock tools are hidden until enable_tools({ groups: ["mocks"] }). A mock targets either the browser or an Electron API, selected with mockType. mockType defaults to browser in WebDriver sessions and is required in Electron sessions. Appium sessions do not support mocks.

ParameterTypeRequiredDescription
mockType"browser" | "electron"Electron sessionsWhich kind of mock to create or read. Defaults to browser in WebDriver sessions
apiNamestringelectron mocksElectron API module, such as dialog, app or clipboard
funcNamestringelectron mocksAPI function, such as showOpenDialog or getName
urlstringbrowser mocksURL glob to intercept, such as **/api/todos
methodstringโ€”Browser mocks only: request method filter, such as get

mockโ€‹

Configures a session-scoped mock. Browser mocks intercept the network requests that match url. They need a BiDi-enabled session, started with capabilities: { webSocketUrl: true }. Electron mocks replace an Electron API function in the main process and need an Electron session.

Omit behavior to observe. The mock then records matching requests without altering them, and you read them with get_mock_calls. An existing mock keeps its configured behavior when you call mock again without one, so use manage_mock with action: "reset" to return it to observe-only.

ParameterTypeRequiredDefaultDescription
behavior"mockReturnValue" | "mockReturnValueOnce" | "mockResolvedValue" | "mockResolvedValueOnce" | "mockRejectedValue" | "mockRejectedValueOnce" (Electron), or "respond" | "respondOnce" | "abort" | "abortOnce" | "redirect" | "redirectOnce" (browser)โ€”Electron: mockReturnValue. Browser: none (observe)What the mock does. Once behaviors apply to the next matching call only
valueany JSONโ€”โ€”Electron: the value to return, resolve or reject with. Browser respond: the response body, required ("" for an empty body). Browser redirect: the target URL, required. Omit for abort and observing
statusCodenumberโ€”โ€”Browser respond behaviors only: response status code
headersobject of stringsโ€”โ€”Browser respond behaviors only: response header overrides

Repeated calls keep the call history. Queued Once values survive further Once calls, but a later sticky behavior (a non-Once behavior such as respond, abort, redirect or mockResolvedValue) replaces the queue.

// Observe every request to the API without changing it
mock({ url: "**/api/**" })
get_mock_calls({ url: "**/api/**" })

// Answer GET requests to the API with an empty list
mock({ url: "**/api/todos", method: "get", behavior: "respond", value: "[]", statusCode: 200, headers: { "content-type": "application/json" } })

// Make the next dialog.showOpenDialog call resolve as cancelled, in an Electron session
mock({ mockType: "electron", apiName: "dialog", funcName: "showOpenDialog", behavior: "mockResolvedValueOnce", value: { canceled: true, filePaths: [] } })

get_mock_callsโ€‹

Reads the arguments of every recorded call for a mock, with the same target fields as mock. Returns { "calls": [...], "callCount": n } as JSON. It fails if no mock exists for that target yet. Read-only.

get_mock_calls({ mockType: "electron", apiName: "dialog", funcName: "showOpenDialog" })

manage_mockโ€‹

Manages an existing mock, with the same target fields as mock. The action decides how far the cleanup goes:

actionEffect
clearRemoves the call history. The configured behavior stays in place
resetRemoves the call history, the configured behavior and any queued Once values. The mock keeps observing
restoreReinstates the original behavior and releases the mock. A later mock call creates it again
manage_mock({ url: "**/api/todos", action: "restore" })

Cloud Providersโ€‹

list_appsโ€‹

Lists apps uploaded to a cloud provider (BrowserStack App Automate, Sauce Labs App Storage, TestMu, TestingBot Storage or Digital.ai Applications). Reads provider-specific credentials from the environment. Sessionless and hidden until enable_tools({ groups: ["cloud-apps"] }).

ParameterTypeRequiredDefaultDescription
provider"browserstack" | "saucelabs" | "testmu" | "testingbot" | "digitalai"โœ“โ€”Cloud provider
sortBy"app_name" | "uploaded_at"โ€”"uploaded_at"Sort order
organizationWidebooleanโ€”false(BrowserStack only) List apps uploaded by all users in the organization
limitnumberโ€”20Max results. Applies when organizationWide is true
region"us-west-1" | "eu-central-1" | "apac-southeast-1"โ€”"eu-central-1"Sauce Labs region
// List apps on each provider
list_apps({ provider: "browserstack" })
list_apps({ provider: "saucelabs", region: "us-west-1" })
list_apps({ provider: "testmu" })
list_apps({ provider: "testingbot" })
list_apps({ provider: "digitalai" })

upload_appโ€‹

Uploads a local .apk or .ipa to a cloud provider (BrowserStack, Sauce Labs, TestMu, TestingBot or Digital.ai). Returns the app URL for use in start_session. Sessionless and hidden until enable_tools({ groups: ["cloud-apps"] }).

ParameterTypeRequiredDefaultDescription
provider"browserstack" | "saucelabs" | "testmu" | "testingbot" | "digitalai"โœ“โ€”Cloud provider
pathstringโœ“โ€”Absolute path to the .apk or .ipa file
customIdstringโ€”โ€”Optional custom ID for referencing the app later
region"us-west-1" | "eu-central-1" | "apac-southeast-1"โ€”"eu-central-1"Sauce Labs region
// Upload to each provider
upload_app({ provider: "browserstack", path: "/path/to/app.apk" })
upload_app({ provider: "saucelabs", path: "/path/to/app.ipa", region: "us-west-1" })
upload_app({ provider: "testmu", path: "/path/to/app.apk" })
upload_app({ provider: "testingbot", path: "/path/to/app.apk" })
upload_app({ provider: "digitalai", path: "/path/to/app.apk" })

Documentationโ€‹

query_docsโ€‹

Searches the official WebdriverIO documentation and returns the most relevant excerpts, each with its page title, section trail, path and score. The corpus is fetched on first use and cached locally. Sessionless, read-only, and listed on every platform. Results come back in TOON format.

Query with 2 to 3 distinctive keywords, not a sentence. appium setup, devtools trace.zip and allure reporter each return the right page first, while a full question dilutes the ranking. A word can also collide with an unrelated page: wire matches Wire Protocol, so if a query misses, retry with the exact page title. To browse instead of searching, read the wdio://docs/index resource for every page title and slug, then wdio://docs/page/{slug} for one page in full.

Cite the path of any page you rely on.

ParameterTypeRequiredDefaultDescription
querystringโœ“โ€”2โ€“3 distinctive keywords: an API name, config key, page title or feature
limitnumberโ€”5Number of results (1โ€“20)
fullPagebooleanโ€”falseReturn the full matched pages instead of excerpts
query_docs({ query: "appium setup" })
query_docs({ query: "devtools trace.zip", fullPage: true, limit: 3 })

Welcome! How can I help?

WebdriverIO AI Copilot