io.github.webdriverio由 GitHub 账号 webdriverio 发布v4.1.0更新于 Oct 30, 2026
MCP server with WebdriverIO for browser and mobile app automation (iOS/Android via Appium)
基于 WebdriverIO 的 MCP 服务器，让助手驱动浏览器、Electron 应用和 iOS/Android 应用：导航、点击、填表、快照与截图。
Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。
参照 仓库 中的启动说明。
A Model Context Protocol (MCP) server that enables AI assistants to interact with web browsers, local Electron applications, and mobile applications using WebdriverIO. Automate Chrome, Firefox, Edge, Safari, Electron, iOS, and Android through a unified interface.
Add the following configuration to your MCP client settings:
Standard config (works in most clients):
[Install in VS Code] [Install in VS Code Insiders] [Install in Cursor]
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS),
%APPDATA%\Claude\claude_desktop_config.json (Windows), or ~/.config/Claude/claude_desktop_config.json (Linux):
Add to your VS Code settings.json or cline_mcp_settings.json file:
Go to Cursor Settings → MCP → Add new MCP Server, or create .cursor/mcp.json:
Use the Codex CLI:
Or edit ~/.codex/config.toml:
Go to Advanced settings → Extensions → Add custom extension, or run:
Or edit ~/.config/goose/config.yaml:
Edit ~/.codeium/windsurf/mcp_config.json:
Edit Zed settings (~/.config/zed/settings.json):
⚠️ Restart Required: After adding the configuration, fully restart your MCP client to apply the changes.
If you prefer to install globally:
Then use wdio-mcp as the command:
📖 Need help? Follow the MCP install guide.
By default the server uses stdio (subprocess) transport. For clients that cannot launch subprocesses (e.g. llama.cpp, OpenAI Codex secure mode), enable HTTP transport:
Then point your MCP client at http://localhost:3000/mcp.
npm install -g appiumappium driver install xcuitest (requires Xcode on macOS)appium driver install uiautomator2 (requires Android Studio)Start the Appium server before using mobile features:
Run browser and mobile app tests on cloud real devices and browsers without any local setup. Currently supports BrowserStack, Sauce Labs, LambdaTest, TestingBot, and Digital.ai Testing.
Set your provider credentials as environment variables or in your MCP client config:
| SAUCE_USERNAME | Sauce Labs username (required) |
| SAUCE_ACCESS_KEY | Sauce Labs access key (required) |
The data center is set per-session via the region parameter in start_session (defaults to eu-central-1).
| TESTMU_USERNAME | LambdaTest username (required) |
| TESTMU_ACCESS_KEY | LambdaTest access key (required) |
| TESTINGBOT_KEY | TestingBot key (required) |
| TESTINGBOT_SECRET | TestingBot secret (required) |
| DIGITALAI_CLOUD_URL | Digital.ai cloud host, e.g. https://your-cloud.example.com (required) |
| DIGITALAI_ACCESS_KEY | Digital.ai access key (required) |
The access key is sent via the digitalai:options capability (mobile) or the flat digitalai:accessKey capability (web).
Report pass/fail status: WebdriverIO defaults to the BiDi protocol, over which Digital.ai's cloud cannot observe command failures — so reports default to "Passed". To make the cloud reflect actual pass/fail, opt in to classic WebDriver per session:
(Pure client-side assertion failures still report as "Passed" — only failures that reach the cloud as WebDriver command errors are detected.)
Mobile (Appium): configure your Digital.ai project for Appium-server execution and pick its default Appium version via the project's "Manage default Appium server version" setting — the version is chosen at the project level (and tracks the versions your cloud supports), so this MCP does not pin one. See Appium Server Test Execution.
Run a browser on a specific OS/version combination:
Provider-specific
os/osVersionbehavior:
- BrowserStack —
osandosVersionmap to separatebstack:options.os/bstack:options.osVersionfields.- Sauce Labs / LambdaTest / TestingBot —
osandosVersionare combined into the W3CplatformNamecapability (e.g.,os: 'Windows'+osVersion: '11'→platformName: 'Windows 11'). These providers useplatformNamevalues like"Windows 11","MacOS Sequoia", or"Linux". TestingBot defaults toWindows 11whenosis omitted.- Digital.ai —
osandosVersionare combined into the flatdigitalai:osNamecapability (NOTplatformName), e.g.os: 'Windows'+osVersion: '11'→digitalai:osName: 'Windows 11'.
Test on cloud real devices. First upload your app (or use an existing app URL):
Run a browser on a cloud mobile device — real device or emulator/simulator — without uploading an app:
Note: Mobile browser sessions do not require
app,appPath, ornoReset. The provider launches a browser directly on the selected device — real or emulator/simulator.
Use list_apps to see previously uploaded apps:
To test against URLs that are only accessible on your local machine or internal network, enable a local tunnel:
The tunnel parameter replaces the deprecated browserstackLocal, saucelabsLocal, and testmuLocal params. Set it to true to auto-start the tunnel (stopped automatically after the session), or 'external' to use a tunnel already running on your machine.
Note: With
tunnel: truethe provider downloads and manages the tunnel binary for you. Fortunnel: 'external'you run it yourself — thewdio://saucelabs/local-binary,wdio://testmu/local-binary, andwdio://testingbot/local-binaryresources provide download URLs and setup instructions. The TestingBot Tunnel is a single cross-platform Java JAR (requires Java 11+) rather than a per-platform binary.
All session types support reporting labels that appear in the provider dashboard:
Both tools require a provider parameter ('browserstack', 'saucelabs', 'testmu', 'testingbot', or 'digitalai').
--remote-debugging-port — ideal for testing
authenticated or pre-configured sessionsThe server lists only the tools that fit the current session: browser sessions get the page tools below, mobile sessions the gestures and device tools, Electron sessions the Electron tools. Rarely used groups (mocks, cookies, device emulation, extensions, attaching, the raw element list, cloud app uploads) are listed after the agent calls enable_tools, so their definitions aren't sent with every request. With several live sessions, tools are listed for the union of their platforms. Set WDIO_MCP_TOOLS=all to list everything up front.
Set WDIO_MCP_NETWORK_LOGS to configure the default Chromium network/performance log capture mode for start_session: none (default, off), failures (Network.loadingFailed and Network.responseReceived entries with HTTP status >= 400), or all (every Chromium performance log entry). Individual sessions can override this default via start_session({ networkLogs: 'none' | 'failures' | 'all' }).
By default the server keeps one session: starting a new one closes the previous one. To run sessions side by side, pass onExisting: "keep" and a name to start_session. The new session is not made the default, so the original keeps answering calls that omit a target.
Every session-bound tool accepts an optional session argument, either a name or a sessionId (sessionId is matched first). Omitting it uses the default session, and targeting a session never changes the default. When a call is targeted, or more than one session is live, the result starts with [session: name (id8)]. Calls to the same session queue and run in order; calls to different sessions run concurrently. An unknown target, or no default session while others are live, returns an error that lists the live sessions. Names are scoped to one server process. The wdio://session/current/* resources always refer to the default session.
click_element, set_value, tap_element and perform_actions take a ref from snapshot (e12) as well as a selector, in browsers and apps, and each result lists what the action changed on the page or screen: new or changed elements with their refs, or the page it navigated to. An agent rarely needs a separate screenshot or snapshot to see the effect.
Recommended workflow (also sent to clients as server instructions):
snapshot, then act with refs.perform_actions call.enable_tools)Example 1: Testing Demo Android App (Book Scanning)
Example 2: Testing World of Books E-commerce Site
Basic web testing prompt:
Browser configuration options:
Mocking is available through mock, get_mock_calls, and manage_mock (listed after enable_tools({ groups: ['mocks'] })), for both Electron main-process API functions and browser network requests.
mockType accepts 'electron' or 'browser'. Browser mocks are the default in WebDriver sessions when mockType is omitted. Electron sessions require an explicit selection because they can target both kinds of mocks. iOS/Android Appium sessions do not support mocking.
Electron behavior defaults to mockReturnValue; mockResolvedValue and mockRejectedValue support async APIs. Each has a Once variant for queued responses. Repeated configuration preserves the existing mock and call history. Values must be JSON; omit value for undefined. clear removes call history, reset also removes behavior and queued responses, and restore reinstates the original function. These tools support individual API functions; class mocks and arbitrary mock implementations are not exposed.
Browser mocks intercept network requests matching a url glob (for example **/api/todos) with an optional method filter. behavior is optional: omit it to passively record matching requests without altering them — the mock still continues every request. respond and respondOnce require value (the JSON response body) and accept optional statusCode and headers; abort/abortOnce fail the request, and redirect/redirectOnce send it to the URL in value. get_mock_calls returns { calls, callCount } for the intercepted requests, and manage_mock takes clear, reset, or restore.
Browser mocks require a BiDi-enabled session — start it with capabilities: { webSocketUrl: true }. Attached sessions default to BiDi off, so browser mocks do not work there unless the attached session negotiated BiDi; in Electron sessions browser mocks additionally require BiDi. Handles belong to the active browser session and cannot be reused after it closes or is replaced. All three tools participate in tracing and generated replay.
Electron support is local-only and uses the official @wdio/electron-service standalone lifecycle. It requires Node.js 22.23.4, 24.22.1, 26.12.1 or a later release of these lines, as the server does. Put service options such as appBinaryPath, appEntryPoint, and appArgs in capabilities['wdio:electronServiceOptions']; use top-level electronRootDir for the service's Electron Builder/Electron Forge discovery. When testing a binary outside the project, set browserVersion to the Electron version so the service can select a compatible Chromedriver.
Existing browser DOM tools work against the Electron renderer. close_session always tears down MCP-managed Electron sessions; detach: true is intentionally unsupported. Main/renderer log capture can be enabled with captureMainProcessLogs or captureRendererLogs plus logDir. To trigger an app deeplink, explicitly configure its URI scheme when starting the Electron session. The scheme has no colon and only URLs with that exact scheme can be dispatched:
Attach to a running Chrome instance:
Connect to an existing WebDriver endpoint:
Use provider: 'external' when another process already owns the browser or webview lifecycle and exposes a W3C
WebDriver endpoint. This is useful for Selenium Grid sessions, externally managed browser drivers, or desktop apps like Tauri apps that
embed a webview and expose WebDriver separately. The MCP server connects to the endpoint; it does not launch or stop the
target application, start tunnels, or manage framework-specific setup.
For desktop webview apps such as Tauri, first start the app and its WebDriver bridge outside of this MCP server, then
pass the endpoint and the required capabilities. For example, a Tauri WebDriver bridge may require
capabilities: {browserName: 'tauri'}.
Attach to an existing WebDriver or Appium session:
Use attach_session when the session has already been created by another process. The MCP reuses the selected provider's
endpoint and credentials, registers the appropriate browser/mobile command set locally, and does not issue a new-session
request. Attached sessions are externally managed: close_session() detaches by default, while
close_session({detach: false}) explicitly terminates the remote session.
An existing cloud session must keep using the tunnel it was created with. attach_session never starts or stops a tunnel,
so keep the original tunnel process alive for as long as the session needs it.
Device emulation (requires BiDi session):
Web extensions (requires BiDi session):
Testing an iOS app on simulator:
Preserving app state between sessions:
Testing an iOS app on real device:
Testing an Android app:
Advanced element detection:
Hybrid app testing (switching contexts):
⚠️ Session Management:
close_session({ detach: true }) to disconnect without terminating the session on the Appium servernoReset and fullReset parameters during session creationnoReset: true or without appPath will automatically detach on closeattach_session always detach on close unless detach: false is explicitly requested⚠️ Task Planning:
⚠️ Mobile Automation:
Web (CSS/XPath):
button.my-class, #element-id//button[@class='my-class']button=Exact text, a*=Contains textMobile (Cross-Platform):
~loginButton (works on both iOS and Android)android=new UiSelector().text("Login")-ios predicate string:label == "Login" AND visible == 1//android.widget.Button[@text="Login"]State Preservation with noReset/fullReset:
Control app state when creating new sessions using the noReset and fullReset parameters:
Example with state preservation:
Detach from Sessions:
The close_session tool supports a detach parameter that disconnects from the session without terminating it on the
Appium server:
Sessions created with noReset: true or without appPath will automatically detach on close.
Sessions adopted with attach_session are externally managed and also detach by default; pass detach: false only when the
MCP should deliberately terminate the existing remote session.
This is particularly useful when:
Both iOS and Android sessions now support automatic handling of system permissions and alerts:
autoGrantPermissions (default: true): Automatically grants app permissions (camera, location, etc.)autoAcceptAlerts (default: true): Automatically accepts system alerts and dialogsautoDismissAlerts (optional): Set to true to dismiss alerts instead of accepting themThis eliminates the need to manually handle permission popups during automated testing.
Every tool call is automatically recorded to a session history. You can inspect sessions and export runnable code via MCP resources — no extra tool calls needed:
wdio://sessions — lists all recorded sessions with type, timestamps, and step countwdio://session/current/steps — step log for the default sessionwdio://session/current/code — generated runnable WebdriverIO JS for the default sessionwdio://session/{sessionId}/steps — step log for any past session by IDwdio://session/{sessionId}/code — generated JS for any past session by IDThe generated script reconstructs the full session — including capabilities, navigation, clicks, and inputs — as a
standalone import { remote } from 'webdriverio' file. For cloud provider sessions it includes the full try/catch/finally
with automatic session result marking via the provider's REST API.
Passing trace: true to start_session produces a Playwright-compatible .trace zip in the .trace/ directory when
the session closes. The zip is playable at player.vibium.dev and shows a filmstrip of
screenshots alongside the action timeline.
How screenshots are timed
Appium's takeScreenshot round-trip takes 700–1300 ms on a local emulator, which is long enough for the previous
action's animations to settle. We exploit this: each screenshot is captured before the next action fires, so what
the Appium server returns is already the settled result of the prior action.
The tricky part is making the trace player show that screenshot under the right action. The player associates a
screencast-frame event with whichever action's time window contains the frame's timestamp field. If the timestamp
is set to "now" (capture time), it falls before the current action's startTime and the player labels it as the
before state of the next action — one action out of sync.
The fix: stamp each screencast-frame with lastAfterEndTime — the endTime of the action that just completed. That
places the frame inside the previous action's window, so the player shows it as the result of that action, not the
precursor to the next one.
The final screenshot at session close is stamped with the last action's endTime, so it renders under that action
rather than appearing as an orphaned frame after the timeline ends.
The wdio://session/current/logs resource returns crash reports, console errors, and system logs for the current
session, auto-detecting the session type to fetch the right log buffer:
Note: Reading this resource clears the log buffer (per the WebDriver spec). Subsequent reads return only entries accumulated since the last read. Browser logs require Chromium (Chrome/Edge) — Firefox and Safari do not support the
getLogscommand.
The response is JSON with sessionType, logTypes (available log types), and entries — each entry includes level,
message, timestamp (Unix ms), and timestampISO.
Browser automation not working?
Mobile automation not working?
appiumadb devices (Android) or Xcode Devices (iOS)Found issues or have suggestions? Please share your feedback!
来源：README.md，提交 214c59a
Start Session
Starts a browser, Electron app or mobile app session (closes the active one unless onExisting: "keep"). Browsers run headless at 1280x800 by default; pass navigationUrl to open a page right away. attach: true connects to a running Chrome via CDP.
osappnameudidtraceattachregiontunnelappPathbrowsernoResetheadless另有 30 个Close Session
Closes the session, or with detach: true disconnects and leaves it running. Attached sessions and Appium sessions with noReset are detached unless detach: false.
detachsessionNavigate to URL
Loads a URL in the current tab and waits for the page load event. Resets page state — DOM, JS runtime, timers, and frame context are destroyed. Use instead of clicking links when the target URL is known.
url必填sessionSwitch Browser Tab
Switches to a tab by handle or 0-based index (see get_tabs). Later tools act on that tab.
indexhandlesessionSwitch Frame
Switches into an iframe (ref or selector), or back to the top page when selector is omitted. Later tools act inside the frame until you switch back. Returns the frame's elements.
sessionselectorScroll Page
Scrolls the page vertically by a pixel amount. Browser-only — for mobile scrolling use swipe. Only supports up/down; no horizontal scrolling.
pixelssessiondirection必填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: take a snapshot to see the new screen. Several steps in a row: perform_actions.
sessionselector必填Set Input Value
Replaces the text of an input or textarea. On web pages the result lists what changed (new elements with refs, or the new page). In apps it does not: take a snapshot to see the new screen. To fill several fields or fill and then click, use one perform_actions call.
value必填sessionselector必填Select Option
Selects an option of a <select> by its text. The result lists what changed on the page. Several steps in a row: perform_actions.
value必填sessionselector必填Press Key
Presses a key or combination in the focused element, e.g. Enter, Tab, Escape, Control+a. The result lists what changed on the page. Several steps in a row: perform_actions.
keys必填timessessionPerform Actions
Runs several actions in one call, e.g. fill a form and submit it, on the page or app screen, and returns what each one changed on web pages. Steps the current session does not support are rejected before any step runs. 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 new refs). value is the text for fill, the option for select and the keys for press.
actions必填sessionPage Snapshot
The page or app screen as an accessibility tree with refs, e.g. `button "Save" [ref=e3]`. Pass refs to perform_actions for several steps, or to click_element/set_value/select_option for one. Default: interactive elements only, plain text is dropped; full: true shows it. find returns only the parts of the page that contain the text (with their refs); full: true includes all text; viewport: true limits it to what is on screen (not together with find).
findfullscopesessionviewportExecute Script
Runs JavaScript in the page (`return` a value; string args that match a selector are passed as elements) or, on Appium, a "mobile: <command>" with args. Prefer the dedicated tools for clicks and typing.
argsscript必填sessionQuery WebdriverIO Docs
Search the official WebdriverIO documentation and return the most relevant excerpts with page, section and source URL. Use before answering any question about WebdriverIO APIs, configuration, services, reporters, selectors, or debugging. Query with 2-3 distinctive keywords, never a sentence: "appium setup", "devtools trace.zip" and "allure reporter" each return the right page first, while "how do I wire up appium in my config file" does not. A word can also collide with an unrelated page — `wire` matches Wire Protocol — so if a query misses, retry with the exact page title, which beats any paraphrase. Set fullPage for the whole page. To browse instead, read wdio://docs/index for every page title and its slug, then wdio://docs/page/{slug} for one page in full. Cite the `path` of any page you rely on.
limitquery必填fullPageGet Screenshot
Takes a screenshot of the current page or screen and returns a base64-encoded image, resized and compressed for model context limits.
sessionGet Browser Tabs
Lists all browser tabs with handle, title, URL, and which is active. Use before switch_tab to find the target handle or index. Browser-only.
sessionEnable Tools
Adds more tools: mocks (mock network requests or Electron APIs); cookies (read, set and delete cookies); device (emulate a phone or tablet, fake the location); extensions (install and open a browser extension); attach (launch Chrome with remote debugging, attach to a running WebDriver or Appium session); elements (raw element list with bounds); cloud-apps (upload and list mobile apps on BrowserStack, Sauce Labs, TestMu, TestingBot, Digital.ai).
groups必填已满足适用检查项的 90%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。
{ "mcpServers": { "wdio-mcp": { "command": "npx", "args": [ "-y", "@wdio/mcp@latest" ] } }}{ "mcpServers": { "wdio-mcp": { "command": "npx", "args": [ "-y", "@wdio/mcp@latest" ] } }}claude mcp add wdio-mcp -- npx -y @wdio/mcp@latest{ "mcpServers": { "wdio-mcp": { "type": "stdio", "command": "npx", "args": [ "-y", "@wdio/mcp@latest" ] } }}{ "mcpServers": { "wdio-mcp": { "command": "npx", "args": [ "-y", "@wdio/mcp@latest" ] } }}codex mcp add wdio-mcp npx "@wdio/mcp@latest"[mcp_servers.wdio-mcp]command = "npx"args = ["@wdio/mcp@latest"]goose configureextensions: wdio-mcp: name: WebDriverIO MCP cmd: npx args: [ -y, "@wdio/mcp@latest" ] enabled: true type: stdio{ "mcpServers": { "wdio-mcp": { "command": "npx", "args": [ "-y", "@wdio/mcp@latest" ] } }}{ "context_servers": { "wdio-mcp": { "source": "custom", "command": "npx", "args": [ "-y", "@wdio/mcp@latest" ] } }}code --add-mcp '{"name":"wdio-mcp","command":"npx","args":["-y","@wdio/mcp@latest"]}'npm install -g @wdio/mcp{ "mcpServers": { "wdio-mcp": { "command": "wdio-mcp" } }}npx @wdio/mcp --http --port 3000appium# Server runs at http://127.0.0.1:4723 by defaultexport BROWSERSTACK_USERNAME=your_usernameexport BROWSERSTACK_ACCESS_KEY=your_access_key{ "mcpServers": { "wdio-mcp": { "command": "npx", "args": ["-y", "@wdio/mcp@latest"], "env": { "BROWSERSTACK_USERNAME": "your_username", "BROWSERSTACK_ACCESS_KEY": "your_access_key" } } }}export SAUCE_USERNAME=your_usernameexport SAUCE_ACCESS_KEY=your_access_key{ "mcpServers": { "wdio-mcp": { "command": "npx", "args": ["-y", "@wdio/mcp@latest"], "env": { "SAUCE_USERNAME": "your_username", "SAUCE_ACCESS_KEY": "your_access_key" } } }}export TESTMU_USERNAME=your_usernameexport TESTMU_ACCESS_KEY=your_access_key{ "mcpServers": { "wdio-mcp": { "command": "npx", "args": ["-y", "@wdio/mcp@latest"], "env": { "TESTMU_USERNAME": "your_username", "TESTMU_ACCESS_KEY": "your_access_key" } } }}export TESTINGBOT_KEY=your_keyexport TESTINGBOT_SECRET=your_secret{ "mcpServers": { "wdio-mcp": { "command": "npx", "args": ["-y", "@wdio/mcp@latest"], "env": { "TESTINGBOT_KEY": "your_key", "TESTINGBOT_SECRET": "your_secret" } } }}export DIGITALAI_CLOUD_URL=https://your-cloud.example.comexport DIGITALAI_ACCESS_KEY=your_access_key{ "mcpServers": { "wdio-mcp": { "command": "npx", "args": ["-y", "@wdio/mcp@latest"], "env": { "DIGITALAI_CLOUD_URL": "https://your-cloud.example.com", "DIGITALAI_ACCESS_KEY": "your_access_key" } } }}start_session({ provider: 'digitalai', platform: 'browser', browser: 'chrome', os: 'Windows 10', capabilities: { 'wdio:enforceWebDriverClassic': true }})// BrowserStackstart_session({ provider: 'browserstack', platform: 'browser', browser: 'chrome', // chrome | firefox | edge | safari browserVersion: 'latest', // default: latest os: 'Windows', // e.g. "Windows", "OS X" osVersion: '11', // e.g. "11", "Sequoia" reporting: { project: 'My Project', build: 'v1.2.0', session: 'Login flow' }})
// Sauce Labsstart_session({ provider: 'saucelabs', platform: 'browser', browser: 'chrome', os: 'Windows', // combined with osVersion → platformName osVersion: '11', // e.g. "11", "15" (numbered Mac naming) region: 'eu-central-1', // default: eu-central-1 reporting: { build: 'v1.2.0', session: 'Login flow' }})
// LambdaTeststart_session({ provider: 'testmu', platform: 'browser', browser: 'chrome', os: 'Windows', // combined with osVersion → platformName osVersion: '11', // e.g. "11", "Sequoia" (optional) reporting: { project: 'My Project', build: 'v1.2.0', session: 'Login flow' }})
// TestingBotstart_session({ provider: 'testingbot', platform: 'browser', browser: 'chrome', os: 'Windows', // combined with osVersion → platformName (default: Windows 11) osVersion: '11', reporting: { build: 'v1.2.0', session: 'Login flow' }})
// Digital.aistart_session({ provider: 'digitalai', platform: 'browser', browser: 'chrome', os: 'Windows', // combined with osVersion → digitalai:osName (optional) osVersion: '11', reporting: { session: 'Login flow' // → digitalai:testName (flat capability, not nested) }})// BrowserStack: returns bs:// URLupload_app({ provider: 'browserstack', path: '/path/to/app.apk' })
// Sauce Labs: returns storage:filename= referenceupload_app({ provider: 'saucelabs', path: '/path/to/app.apk' })
// LambdaTest: returns lt:// URLupload_app({ provider: 'testmu', path: '/path/to/app.apk' })
// TestingBot: returns tb:// URLupload_app({ provider: 'testingbot', path: '/path/to/app.apk' })
// Digital.ai: returns cloud:<package-or-bundle> referenceupload_app({ provider: 'digitalai', path: '/path/to/app.apk' })
// Start a sessionstart_session({ provider: 'browserstack', platform: 'android', app: 'bs://abc123...', deviceName: 'Samsung Galaxy S23', platformVersion: '13.0'})
// Sauce Labs native appstart_session({ provider: 'saucelabs', platform: 'android', app: 'storage:filename=myapp.apk', deviceName: 'Samsung.*', platformVersion: '16'})
// LambdaTest native appstart_session({ provider: 'testmu', platform: 'android', app: 'lt://abc123...', deviceName: 'Pixel 7', platformVersion: '13'})
// TestingBot native appstart_session({ provider: 'testingbot', platform: 'android', app: 'tb://abc123...', deviceName: 'Pixel 7', platformVersion: '13'})
// Digital.ai native app — devices are selected via a deviceQuerystart_session({ provider: 'digitalai', platform: 'android', app: 'cloud:com.example.app', deviceQuery: "@os='android' and @version='14' and @name='.*Pixel.*'" // or omit deviceQuery and pass deviceName / platformVersion to build one})// BrowserStack — Chrome on Android emulatorstart_session({ provider: 'browserstack', platform: 'android', browser: 'chrome', deviceName: 'Google Pixel 7', platformVersion: '13'})
// Sauce Labs — Safari on iOS simulatorstart_session({ provider: 'saucelabs', platform: 'ios', browser: 'safari', deviceName: 'iPhone 15', platformVersion: '18', region: 'eu-central-1'})
// LambdaTest — Chrome on Android emulatorstart_session({ provider: 'testmu', platform: 'android', browser: 'chrome', deviceName: 'Pixel 7', platformVersion: '13'})
// TestingBot — Chrome on Android emulatorstart_session({ provider: 'testingbot', platform: 'android', browser: 'chrome', deviceName: 'Pixel 7', platformVersion: '13'})
// Digital.ai — Chrome on an Android device (real or emulator; selected via a deviceQuery)start_session({ provider: 'digitalai', platform: 'android', browser: 'chrome', deviceName: 'Pixel 7', platformVersion: '13' // or omit deviceName / platformVersion and pass deviceQuery directly, e.g. // deviceQuery: "@os='android' and @emulator='true'" to force an emulator})list_apps({ provider: 'browserstack' })list_apps({ provider: 'saucelabs', sortBy: 'app_name' })list_apps({ provider: 'testmu' })list_apps({ provider: 'testingbot' })list_apps({ provider: 'digitalai' })list_apps({ provider: 'browserstack', organizationWide: true })// Auto-start tunnel (provider manages lifecycle)start_session({ provider: 'saucelabs', platform: 'browser', tunnel: true // auto-starts tunnel before session})
// Use an already-running tunnelstart_session({ provider: 'saucelabs', platform: 'browser', tunnel: 'external' // uses existing tunnel})start_session({ platform: "browser", browser: "chrome", name: "alice" })start_session({ platform: "browser", browser: "chrome", name: "bob", onExisting: "keep" })navigate({ url: "https://example.com", session: "bob" })Test the Demo Android app at C:\Users\demo-liveApiGbRegionNonMinifiedRelease-3018788.apk on emulator-5554:1. Start the app with auto-grant permissions2. Get visible elements on the onboarding screen3. Tap "Skip" to bypass onboarding4. Verify main screen loads5. Take a screenshotYou are a Testing expert, and want to assess the basic workflows of worldofbooks.com:- Open World of Books (accept all cookies)- Get visible elements to see navigation structure- Search for a fiction book- Choose one and validate if there are NEW and used book options- Report your findings at the endYou are a Testing expert, and want to assess the basic workflows of a web application:- Open World of Books (accept all cookies)- Search for a fiction book- Choose one and validate if there are NEW and used book options- Report your findings at the end// Default settings (headed mode, 1280x1080)start_session({platform: 'browser'})
// Firefoxstart_session({platform: 'browser', browser: 'firefox'})
// Edgestart_session({platform: 'browser', browser: 'edge'})
// Safari (headed only; requires macOS)start_session({platform: 'browser', browser: 'safari'})
// Headless modestart_session({platform: 'browser', headless: true})
// Custom dimensionsstart_session({platform: 'browser', windowWidth: 1920, windowHeight: 1080})
// Pass custom capabilities (e.g. Chrome extensions, profile, prefs)start_session({ platform: 'browser', headless: false, capabilities: { 'goog:chromeOptions': { args: ['--user-data-dir=/tmp/wdio-mcp-profile', '--load-extension=/path/to/unpacked-extension'] } }})mock({ mockType: 'electron', apiName: 'dialog', funcName: 'showOpenDialog', behavior: 'mockResolvedValue', value: { canceled: false, filePaths: ['/tmp/example.txt'] }})// Interact with the renderer to open the application's file picker, then inspect its calls.get_mock_calls({ mockType: 'electron', apiName: 'dialog', funcName: 'showOpenDialog' })manage_mock({ mockType: 'electron', apiName: 'dialog', funcName: 'showOpenDialog', action: 'restore' })start_session({ platform: 'browser', browser: 'chrome', capabilities: { webSocketUrl: true } })
// Observe-only: record every request to /api/todos without changing responses.mock({ mockType: 'browser', url: '**/api/todos' })navigate({ url: 'https://example.com/todos' })get_mock_calls({ mockType: 'browser', url: '**/api/todos' })
// Or overwrite the response instead.mock({ mockType: 'browser', url: '**/api/todos', method: 'GET', behavior: 'respond', value: [{ id: 1, title: 'Buy milk' }], statusCode: 200 })
// Interact with the page, then inspect the intercepted requests.get_mock_calls({ mockType: 'browser', url: '**/api/todos', method: 'GET' })manage_mock({ mockType: 'browser', url: '**/api/todos', method: 'GET', action: 'restore' })start_session({ platform: 'electron', browserVersion: '33.2.1', capabilities: { 'wdio:electronServiceOptions': { appBinaryPath: '/path/to/MyApp.app/Contents/MacOS/MyApp', appArgs: ['--disable-gpu'] } }})
// Privileged: this code runs in the Electron main process, not the renderer.execute_electron_script({ script: 'return electron.app.getName()' })start_session({ platform: 'electron', electronDeeplinkScheme: 'myapp', capabilities: { 'wdio:electronServiceOptions': { appBinaryPath: '/path/to/MyApp.app/Contents/MacOS/MyApp' } }})trigger_electron_deeplink({ url: 'myapp://open/item' })// First, launch Chrome with remote debugging enabled://// macOS (must quit Chrome first — open -a ignores args if Chrome is already running):// pkill -x "Google Chrome" && sleep 1// /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \// --remote-debugging-port=9222 \// --user-data-dir=/tmp/chrome-debug &//// Linux:// google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug &//// Verify it's ready: curl http://localhost:9222/json/versionstart_session({attach: true})start_session({attach: true, port: 9333})start_session({attach: true, port: 9222, navigationUrl: 'https://app.example.com'})// Defaults to http://127.0.0.1:4445/ and browserName: 'chrome'start_session({provider: 'external', platform: 'browser'})
// Custom WebDriver endpoint and capabilitiesstart_session({ provider: 'external', platform: 'browser', webdriverConfig: { protocol: 'http', hostname: '127.0.0.1', port: 4445, path: '/' }, capabilities: { browserName: 'tauri' }})// Existing BrowserStack App Automate sessionattach_session({ provider: 'browserstack', platform: 'ios', sessionId: 'existing-browserstack-session-id', capabilities: { 'appium:deviceName': 'iPhone 15', 'appium:automationName': 'XCUITest' }})
// Existing session on a local Appium serverattach_session({ provider: 'local', platform: 'android', sessionId: 'existing-appium-session-id', appiumConfig: { protocol: 'http', host: '127.0.0.1', port: 4723, path: '/' }})
// Existing mobile session on a custom W3C WebDriver endpointattach_session({ provider: 'external', platform: 'ios', sessionId: 'existing-grid-session-id', webdriverConfig: { protocol: 'https', hostname: 'grid.example.com', port: 443, path: '/wd/hub' }})// Device emulation (requires BiDi session)start_session({capabilities: {webSocketUrl: true}})emulate_device() // list available presetsemulate_device({device: 'iPhone 15'}) // activate emulationemulate_device({device: 'Pixel 7'}) // switch deviceemulate_device({device: 'reset'}) // restore desktop defaultsstart_session({platform: 'browser', browser: 'chrome', capabilities: {webSocketUrl: true}})
open_web_extension({ extensionData: {type: 'path', path: '/path/to/unpacked-extension'}, path: 'options.html'})
// Drive the extension UI with the normal page tools.get_elements()click_element({selector: '#save'})
// For remote/cloud sessions, send a packaged extension archive as base64.open_web_extension({ extensionData: {type: 'base64', value: '<base64-encoded-zip>'}, path: 'options.html'})Test my iOS app located at /path/to/MyApp.app on iPhone 15 Pro simulator:1. Start the app session2. Tap the login button3. Enter "testuser" in the username field4. Take a screenshot of the home screen5. Close the sessionTest my Android app without resetting data:1. Start app session with noReset: true and fullReset: false2. App launches with existing login state and user data preserved3. Run test scenarios4. Close session (app remains installed with data intact)Test my iOS app on my physical iPhone:1. Start app session with: - platform: iOS - appPath: /path/to/MyApp.ipa - deviceName: My iPhone - udid: 00008030-001234567890ABCD (your device's UDID) - platformVersion: 17.02. Run your test scenario3. Close the sessionTest my Android app /path/to/app.apk on the Pixel_6_API_34 emulator:1. Start the app with auto-grant permissions2. Get visible elements (use inViewportOnly: false to see all elements)3. Swipe up to scroll4. Tap on the "Settings" button using text matching5. Verify the settings screen is displayedTest my app and debug layout issues:1. Start the app session2. Get visible elements with includeContainers: true to see the layout hierarchy3. Analyze ViewGroup, FrameLayout, and ScrollView containers4. Use inViewportOnly: false to find off-screen elements that need scrollingTest my hybrid app:1. Start the Android app session2. Tap "Open Web" button in native context3. List available contexts4. Switch to WEBVIEW context5. Click the login button using CSS selector6. Switch back to NATIVE_APP context7. Verify we're back on the home screen// Preserve login state between test runsstart_session({ platform: 'android', appPath: '/path/to/app.apk', deviceName: 'emulator-5554', noReset: true, // Don't reset app state fullReset: false, // Don't uninstall autoGrantPermissions: true, capabilities: { 'appium:chromedriverExecutable': '/path/to/chromedriver', 'appium:autoWebview': true }})// App launches with existing user data, login tokens, preferences intact// Detach without killing the sessionclose_session({detach: true})
// Explicit session termination (closes the app and removes session)close_session({detach: false})Timeline (monotonic ms):
prev.endTime ← frame timestamp stamped here │ │ [screenshot captured here — shows settled state after prev action] │ curr.startTime │ │ [action executes] │ curr.endTime ← next frame will be stamped here