WebdriverIO MCP

WebDriverIO MCP サーバー

AI アシスタントが WebdriverIO を使用して、ウェブブラウザー、ローカルの Electron アプリケーション、モバイルアプリケーションを操作できるようにする Model Context Protocol（MCP）サーバーです。統一されたインターフェースから、Chrome、Firefox、Edge、Safari、Electron、iOS、Android を自動化できます。

インストール

以下の設定を MCP クライアントの設定に追加してください。

標準設定（ほとんどのクライアントで動作します）：

{
  "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 configure

extensions:
  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"]}'

⚠️ 再起動が必要です：設定を追加した後、変更を適用するには MCP クライアントを完全に再起動してください。

オプション 2：グローバルインストール

グローバルにインストールする場合：

npm install -g @wdio/mcp

その後、コマンドとして wdio-mcp を使用します。

{
  "mcpServers": {
    "wdio-mcp": {
      "command": "wdio-mcp"
    }
  }
}

📖 お困りですか？ MCP インストールガイドをご覧ください。

HTTP トランスポート（サブプロセスを使用しないクライアント向け）

デフォルトでは、サーバーは stdio（サブプロセス）トランスポートを使用します。サブプロセスを起動できないクライアント（例： llama.cpp、OpenAI Codex のセキュアモード）では、HTTP トランスポートを有効にしてください。

npx @wdio/mcp --http --port 3000

MCP クライアントの接続先を http://localhost:3000/mcp に設定してください。

モバイルアプリ自動化の前提条件

• Appium Server：npm install -g appium でグローバルにインストールします
• プラットフォームドライバー：
  • iOS：appium driver install xcuitest（macOS 上の Xcode が必要です）
  • Android：appium driver install uiautomator2（Android Studio が必要です）
• デバイス／エミュレーター：
  • iOS シミュレーター（macOS）または実機
  • Android エミュレーターまたは実機
• iOS 実機の場合：デバイスの UDID（Unique Device Identifier）が必要です
  • macOS で UDID を確認する方法：デバイスを接続 → Finder を開く → デバイスを選択 → デバイス名／モデル名をクリックして UDID を表示します
  • Windows で UDID を確認する方法：デバイスを接続 → iTunes または Apple Devices アプリを開く → デバイスアイコンをクリック → 「Serial Number」をクリックして UDID を表示します
  • Xcode で確認する方法：Window → Devices and Simulators → デバイスを選択 → 「Identifier」として UDID が表示されます

モバイル機能を使用する前に、Appium サーバーを起動してください。

appium
# Server runs at http://127.0.0.1:4723 by default

クラウドプロバイダー

ローカル環境をセットアップすることなく、クラウド上の実機やブラウザーでブラウザーおよびモバイルアプリのテストを実行できます。現在、BrowserStack、Sauce Labs、 LambdaTest、TestingBot、および Digital.ai Testing に対応しています。

前提条件

プロバイダーの認証情報を環境変数または MCP クライアントの設定に指定します。

export BROWSERSTACK_USERNAME=your_username
export 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_username
export 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_username
export 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_key
export 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.com
export 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 }
})

ブラウザーセッション

特定の OS／バージョンの組み合わせでブラウザーを実行します。

// BrowserStack
start_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 Labs
start_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'
    }
})

// LambdaTest
start_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'
    }
})

// TestingBot
start_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.ai
start_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)
    }
})

プロバイダーごとの os / osVersion の動作：

• BrowserStack — os と osVersion は、それぞれ bstack:options.os / bstack:options.osVersion フィールドにマッピングされます。
• Sauce Labs / LambdaTest / TestingBot — os と osVersion は、W3C の platformName 機能に結合されます（例：os: 'Windows' + osVersion: '11' → platformName: 'Windows 11'）。これらのプロバイダーでは、"Windows 11"、"MacOS Sequoia"、"Linux" などの platformName 値を使用します。TestingBot では、os を省略するとデフォルトで Windows 11 になります。
• Digital.ai — os と osVersion は、フラットな digitalai:osName 機能に結合されます（platformName ではありません）。例：os: 'Windows' + osVersion: '11' → digitalai:osName: 'Windows 11'。

モバイルアプリのセッション

クラウド上の実機でテストします。まずアプリをアップロードするか、既存のアプリ URL を使用します。

// BrowserStack: returns bs:// URL
upload_app({ provider: 'browserstack', path: '/path/to/app.apk' })

// Sauce Labs: returns storage:filename= reference
upload_app({ provider: 'saucelabs', path: '/path/to/app.apk' })

// LambdaTest: returns lt:// URL
upload_app({ provider: 'testmu', path: '/path/to/app.apk' })

// TestingBot: returns tb:// URL
upload_app({ provider: 'testingbot', path: '/path/to/app.apk' })

// Digital.ai: returns cloud:<package-or-bundle> reference
upload_app({ provider: 'digitalai', path: '/path/to/app.apk' })

// Start a session
start_session({
    provider: 'browserstack',
    platform: 'android',
    app: 'bs://abc123...',
    deviceName: 'Samsung Galaxy S23',
    platformVersion: '13.0'
})

// Sauce Labs native app
start_session({
    provider: 'saucelabs',
    platform: 'android',
    app: 'storage:filename=myapp.apk',
    deviceName: 'Samsung.*',
    platformVersion: '16'
})

// LambdaTest native app
start_session({
    provider: 'testmu',
    platform: 'android',
    app: 'lt://abc123...',
    deviceName: 'Pixel 7',
    platformVersion: '13'
})

// TestingBot native app
start_session({
    provider: 'testingbot',
    platform: 'android',
    app: 'tb://abc123...',
    deviceName: 'Pixel 7',
    platformVersion: '13'
})

// Digital.ai native app — devices are selected via a deviceQuery
start_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 emulator
start_session({
    provider: 'browserstack',
    platform: 'android',
    browser: 'chrome',
    deviceName: 'Google Pixel 7',
    platformVersion: '13'
})

// Sauce Labs — Safari on iOS simulator
start_session({
    provider: 'saucelabs',
    platform: 'ios',
    browser: 'safari',
    deviceName: 'iPhone 15',
    platformVersion: '18',
    region: 'eu-central-1'
})

// LambdaTest — Chrome on Android emulator
start_session({
    provider: 'testmu',
    platform: 'android',
    browser: 'chrome',
    deviceName: 'Pixel 7',
    platformVersion: '13'
})

// TestingBot — Chrome on Android emulator
start_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
})

注： モバイルブラウザーセッションでは、app、appPath、noReset は不要です。プロバイダーは、選択した実機またはエミュレーター／シミュレーターでブラウザーを直接起動します。

list_apps を使うと、以前アップロードしたアプリを確認できます。

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 })

ローカルトンネル

ローカルマシンまたは内部ネットワークからしかアクセスできない URL に対してテストするには、ローカルトンネルを有効にします。

// Auto-start tunnel (provider manages lifecycle)
start_session({
    provider: 'saucelabs',
    platform: 'browser',
    tunnel: true                  // auto-starts tunnel before session
})

// Use an already-running tunnel
start_session({
    provider: 'saucelabs',
    platform: 'browser',
    tunnel: 'external'            // uses existing tunnel
})

tunnel パラメーターは、非推奨の browserstackLocal、saucelabsLocal、testmuLocal パラメーターに代わるものです。true に設定するとトンネルが自動的に起動します（セッション後に自動停止します）。'external' に設定すると、マシン上ですでに実行中のトンネルを使用します。

注：tunnel: true の場合、プロバイダーがトンネルのバイナリをダウンロードして管理します。tunnel: 'external' の場合は、トンネルを自分で実行します。wdio://saucelabs/local-binary、wdio://testmu/local-binary、wdio://testingbot/local-binary リソースには、ダウンロード URL とセットアップ手順が記載されています。TestingBot Tunnel は、プラットフォームごとのバイナリではなく、クロスプラットフォーム対応の単一の Java JAR です（Java 11 以降が必要です）。

レポート用ラベル

すべてのセッションタイプで、プロバイダーダッシュボードに表示される reporting ラベルを使用できます。

クラウドプロバイダーツール

どちらのツールにも provider パラメーター（'browserstack'、'saucelabs'、'testmu'、'testingbot'、または 'digitalai'）が必要です。

機能

ブラウザー自動化

• セッション管理：ヘッドレス／ヘッドありモードでブラウザーセッション（Chrome、Firefox、Edge、Safari）を開始および終了します
• ナビゲーションと操作：URL に移動し、要素をクリックし、フォームに入力し、コンテンツを取得します
• ページ分析：表示中の要素やアクセシビリティツリーを取得し、スクリーンショットを撮影します
• Cookie 管理：Cookie の取得、設定、削除を行います
• スクロール：距離を設定できるスムーズなスクロールを行います
• 実行中の Chrome に接続：--remote-debugging-port を介して既存の Chrome ウィンドウに接続します。認証済みまたは事前設定済みのセッションのテストに最適です
• 既存の WebDriver エンドポイントに接続：フレームワークが管理するブラウザーや、Tauri などのデスクトップ WebView 自動化ブリッジといった、すでに実行中の Selenium 互換 WebDriver エンドポイントを再利用します
• デバイスエミュレーション：モバイル／タブレットのプリセット（iPhone 15、Pixel 7 など）を適用し、実機を使わずにレスポンシブレイアウトをシミュレートします
• セッション記録：すべてのツール呼び出しを自動的に記録し、実行可能な WebdriverIO JS としてエクスポートできます

モバイルアプリの自動化（iOS／Android）

• ネイティブアプリのテスト：Appium を介して iOS（.app／.ipa）および Android（.apk）アプリをテストします
• タッチジェスチャー：タップ、スワイプ、長押し、ドラッグ＆ドロップを行います
• アプリのライフサイクル：アプリの起動、バックグラウンドへの移行、終了、状態確認を行います
• コンテキスト切り替え：ハイブリッドアプリのネイティブコンテキストと WebView コンテキストをシームレスに切り替えます
• デバイス制御：画面の回転、ロック／ロック解除、位置情報、キーボード操作、通知に対応します
• クロスプラットフォームセレクター：アクセシビリティ ID、XPath、UiAutomator（Android）、Predicates（iOS）に対応します

利用可能なツール

サーバーには、現在のセッションに適したツールのみが一覧表示されます。ブラウザーセッションでは以下のページツール、モバイルセッションではジェスチャーとデバイスのツール、Electron セッションでは Electron のツールが表示されます。使用頻度の低いグループ（モック、Cookie、デバイスエミュレーション、拡張機能、アタッチ、生の要素リスト、クラウドアプリのアップロード）は、エージェントが enable_tools を呼び出した後に一覧表示されるため、すべてのリクエストで定義が送信されるわけではありません。最初からすべてを一覧表示するには、WDIO_MCP_TOOLS=all を設定します。

セッション管理

ナビゲーションとページ操作（Web とモバイル）

要素の操作（Web およびモバイル）

click_element、set_value、tap_element、perform_actions は、ブラウザーとアプリの両方で、セレクターに加えて snapshot の ref（e12）も受け取ります。また、それぞれの結果には、ページまたは画面でアクションによって変更された内容（新規または変更された要素とその ref、または遷移先のページ）が記載されます。エージェントが効果を確認するために、別途スクリーンショットやスナップショットを取得する必要はほとんどありません。

推奨ワークフロー（サーバーの指示としてクライアントにも送信されます）：

• snapshot を実行してから、ref を使って操作します。
• 連続する複数の手順（フォームへの入力後に送信するなど）には、perform_actions を1回呼び出します。
• 最新の結果で得た ref は、ページが変わるまで有効です。

Cookie の管理（enable_tools 実行後のWeb）

モバイルジェスチャー（iOS/Android）

コンテキストの切り替え（ハイブリッドアプリ）

デバイスの制御（iOS/Android）

ドキュメント検索

MCP リソース（読み取り専用、ツール呼び出しは不要）

使用例

実際のテストケース

例 1：デモ用 Android アプリのテスト（書籍のスキャン）

Test the Demo Android app at C:\Users\demo-liveApiGbRegionNonMinifiedRelease-3018788.apk on emulator-5554:
1. Start the app with auto-grant permissions
2. Get visible elements on the onboarding screen
3. Tap "Skip" to bypass onboarding
4. Verify main screen loads
5. Take a screenshot

例 2：World of Books の E コマースサイトのテスト

You 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 end

ブラウザーの自動化

基本的な Web テストのプロンプト：

You 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'})

// Firefox
start_session({platform: 'browser', browser: 'firefox'})

// Edge
start_session({platform: 'browser', browser: 'edge'})

// Safari (headed only; requires macOS)
start_session({platform: 'browser', browser: 'safari'})

// Headless mode
start_session({platform: 'browser', headless: true})

// Custom dimensions
start_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']
        }
    }
})

モック

Electron のメインプロセス API 関数とブラウザーのネットワークリクエストの両方で、mock、get_mock_calls、manage_mock（enable_tools({ groups: ['mocks'] })の後に表示）を使ってモックを利用できます。

mockTypeには'electron'または'browser'を指定します。mockTypeを省略した場合、WebDriver セッションではブラウザーのモックがデフォルトになります。Electron セッションでは両方の種類のモックを対象にできるため、明示的な選択が必要です。iOS／Android の Appium セッションではモックを利用できません。

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' })

Electron のbehaviorはデフォルトでmockReturnValueです。非同期 API ではmockResolvedValueとmockRejectedValueをサポートしています。それぞれに、応答をキューに追加するOnceバリアントがあります。設定を繰り返しても、既存のモックと呼び出し履歴は保持されます。値は JSON で指定する必要があります。undefinedの場合はvalueを省略してください。clearは呼び出し履歴を削除し、resetはさらに動作とキューに追加された応答を削除します。restoreは元の関数を復元します。これらのツールは個々の API 関数に対応しています。クラスのモックや任意のモック実装は公開されていません。

ブラウザーのモックは、urlのグロブ（例：**/api/todos）に一致するネットワークリクエストを、任意のmethodフィルターとともにインターセプトします。behaviorは任意です。省略すると、一致するリクエストを変更せずに受動的に記録します。モックは引き続きすべてのリクエストを処理します。respondとrespondOnceにはvalue（JSON のレスポンス本文）が必要で、任意のstatusCodeとheadersを指定できます。abort／abortOnceはリクエストを失敗させ、redirect／redirectOnceはvalueで指定した URL にリクエストを送ります。get_mock_callsはインターセプトしたリクエストについて{ calls, callCount }を返します。manage_mockにはclear、reset、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' })

ブラウザーのモックには、BiDi が有効なセッションが必要です。capabilities: { webSocketUrl: true }を指定してセッションを開始してください。アタッチされたセッションではデフォルトで BiDi が無効なため、そのセッションで BiDi がネゴシエートされていない限り、ブラウザーのモックは機能しません。Electron セッションでは、ブラウザーのモックにも BiDi が必要です。ハンドルはアクティブなブラウザーセッションに属し、そのセッションが閉じられた後や置き換えられた後は再利用できません。3つのツールはすべて、トレースと生成されたリプレイに対応しています。

Electron アプリケーション

Electron のサポートはローカルのみで、公式の @wdio/electron-service のスタンドアロンライフサイクルを使用します。サーバーと同様に、Node.js 22.23.4、24.22.1、26.12.1、またはこれらの系列のそれ以降のリリースが必要です。appBinaryPath、appEntryPoint、appArgs などのサービスオプションは capabilities['wdio:electronServiceOptions'] に設定し、サービスが Electron Builder／Electron Forge を検出できるよう、トップレベルの electronRootDir を使用してください。プロジェクト外のバイナリをテストする場合は、サービスが互換性のある Chromedriver を選択できるよう、browserVersion に Electron のバージョンを設定してください。

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()' })

既存のブラウザー DOM ツールは Electron のレンダラーに対して動作します。close_session は常に MCP が管理する Electron セッションを終了します。detach: true は意図的にサポートされていません。captureMainProcessLogs または captureRendererLogs と logDir を指定すると、メイン／レンダラーのログキャプチャを有効にできます。アプリのディープリンクを実行するには、Electron セッションの開始時に URI スキームを明示的に設定してください。スキームにはコロンを含めず、そのスキームと完全に一致する URL のみをディスパッチできます。

start_session({
  platform: 'electron',
  electronDeeplinkScheme: 'myapp',
  capabilities: {
    'wdio:electronServiceOptions': {
      appBinaryPath: '/path/to/MyApp.app/Contents/MacOS/MyApp'
    }
  }
})
trigger_electron_deeplink({ url: 'myapp://open/item' })

実行中の Chrome インスタンスにアタッチする：

// 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/version
start_session({attach: true})
start_session({attach: true, port: 9333})
start_session({attach: true, port: 9222, navigationUrl: 'https://app.example.com'})

既存の WebDriver エンドポイントに接続する：

別のプロセスがすでにブラウザーまたは WebView のライフサイクルを管理しており、W3C WebDriver エンドポイントを公開している場合は、provider: 'external' を使用してください。Selenium Grid セッション、外部管理のブラウザードライバー、または WebView を埋め込み、WebDriver を別途公開する Tauri アプリなどのデスクトップアプリで役立ちます。MCP サーバーはエンドポイントに接続しますが、対象アプリケーションの起動や停止、トンネルの開始、フレームワーク固有のセットアップ管理は行いません。

// Defaults to http://127.0.0.1:4445/ and browserName: 'chrome'
start_session({provider: 'external', platform: 'browser'})

// Custom WebDriver endpoint and capabilities
start_session({
    provider: 'external',
    platform: 'browser',
    webdriverConfig: {
        protocol: 'http',
        hostname: '127.0.0.1',
        port: 4445,
        path: '/'
    },
    capabilities: {
        browserName: 'tauri'
    }
})

Tauri などのデスクトップ WebView アプリの場合は、まずこの MCP サーバーの外部でアプリと WebDriver ブリッジを起動し、その後、エンドポイントと必要な機能を渡してください。たとえば、Tauri WebDriver ブリッジでは capabilities: {browserName: 'tauri'} が必要な場合があります。

既存の WebDriver または Appium セッションにアタッチする：

別のプロセスがすでにセッションを作成している場合は、attach_session を使用してください。MCP は選択したプロバイダーの エンドポイントと認証情報を再利用し、適切なブラウザー／モバイルコマンドセットをローカルに登録します。新しいセッションの リクエストは送信しません。アタッチしたセッションは外部で管理されます。close_session() はデフォルトでデタッチし、 close_session({detach: false}) はリモートセッションを明示的に終了します。

// Existing BrowserStack App Automate session
attach_session({
    provider: 'browserstack',
    platform: 'ios',
    sessionId: 'existing-browserstack-session-id',
    capabilities: {
        'appium:deviceName': 'iPhone 15',
        'appium:automationName': 'XCUITest'
    }
})

// Existing session on a local Appium server
attach_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 endpoint
attach_session({
    provider: 'external',
    platform: 'ios',
    sessionId: 'existing-grid-session-id',
    webdriverConfig: {
        protocol: 'https',
        hostname: 'grid.example.com',
        port: 443,
        path: '/wd/hub'
    }
})

既存のクラウドセッションでは、作成時に使用したトンネルを引き続き使用する必要があります。attach_session はトンネルを開始も停止もしないため、セッションが必要とする間は元のトンネルプロセスを実行したままにしてください。

デバイスエミュレーション（BiDi セッションが必要）：

// Device emulation (requires BiDi session)
start_session({capabilities: {webSocketUrl: true}})
emulate_device()                         // list available presets
emulate_device({device: 'iPhone 15'})    // activate emulation
emulate_device({device: 'Pixel 7'})      // switch device
emulate_device({device: 'reset'})        // restore desktop defaults

Web 拡張機能（BiDi セッションが必要）：

start_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'
})

モバイルアプリの自動化

シミュレーターで iOS アプリをテストする：

Test my iOS app located at /path/to/MyApp.app on iPhone 15 Pro simulator:
1. Start the app session
2. Tap the login button
3. Enter "testuser" in the username field
4. Take a screenshot of the home screen
5. Close the session

セッション間でアプリの状態を保持する：

Test my Android app without resetting data:
1. Start app session with noReset: true and fullReset: false
2. App launches with existing login state and user data preserved
3. Run test scenarios
4. Close session (app remains installed with data intact)

実機で iOS アプリをテストする：

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.0
2. Run your test scenario
3. Close the session

Android アプリをテストする：

Test my Android app /path/to/app.apk on the Pixel_6_API_34 emulator:
1. Start the app with auto-grant permissions
2. Get visible elements (use inViewportOnly: false to see all elements)
3. Swipe up to scroll
4. Tap on the "Settings" button using text matching
5. Verify the settings screen is displayed

高度な要素検出：

Test my app and debug layout issues:
1. Start the app session
2. Get visible elements with includeContainers: true to see the layout hierarchy
3. Analyze ViewGroup, FrameLayout, and ScrollView containers
4. Use inViewportOnly: false to find off-screen elements that need scrolling

ハイブリッドアプリのテスト（コンテキストの切り替え）：

Test my hybrid app:
1. Start the Android app session
2. Tap "Open Web" button in native context
3. List available contexts
4. Switch to WEBVIEW context
5. Click the login button using CSS selector
6. Switch back to NATIVE_APP context
7. Verify we're back on the home screen

重要な注意事項

⚠️ セッション管理：

• 一度にアクティブにできるセッションは1つ（ブラウザーまたはアプリ）だけです
• システムリソースを解放するため、作業が終わったら必ずセッションを閉じてください
• ブラウザーとモバイルを切り替える場合は、先に現在のセッションを閉じてください
• close_session({ detach: true }) を使用すると、Appium サーバー上のセッションを終了せずに切断できます
• セッション作成時の noReset と fullReset パラメーターで、状態の保持を制御できます
• noReset: true を指定したセッション、または appPath を指定せずに作成したセッションは、終了時に自動的に切断されます
• attach_session で接続したセッションは、detach: false を明示的に指定しない限り、終了時に切断されます

⚠️ タスクの計画：

• 複雑な自動化は、焦点を絞った小さな操作に分割してください
• 大規模な自動化では、Claude のメッセージ上限をすぐに使い切る場合があります

⚠️ モバイル自動化：

• モバイルセッションを開始する前に、Appium サーバーを起動しておく必要があります
• エミュレーター／シミュレーターが起動しており、デバイスが接続されていることを確認してください
• iOS の自動化には、Xcode がインストールされた macOS が必要です
• iOS 実機：iOS 実機でのテストには、デバイスの UDID（40 文字の一意な識別子）が必要です。UDID の確認方法については、「前提条件」セクションを参照してください

セレクター構文のクイックリファレンス

Web（CSS／XPath）：

• CSS：button.my-class、#element-id
• XPath：//button[@class='my-class']
• テキスト：button=Exact text、a*=Contains text

モバイル（クロスプラットフォーム）：

• アクセシビリティ ID：~loginButton（iOS と Android の両方で動作します）
• Android UiAutomator：android=new UiSelector().text("Login")
• iOS Predicate：-ios predicate string:label == "Login" AND visible == 1
• XPath：//android.widget.Button[@text="Login"]

高度な機能

アプリ状態の保持

noReset/fullReset による状態の保持： noReset と fullReset パラメーターを使用して、新しいセッションの作成時にアプリの状態を制御します。

状態を保持する例：

// Preserve login state between test runs
start_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

セッションからの切断： close_session ツールは detach パラメーターをサポートしており、Appium サーバー上のセッションを終了せずに切断できます。

// Detach without killing the session
close_session({detach: true})

// Explicit session termination (closes the app and removes session)
close_session({detach: false})

noReset: true を指定したセッション、または appPath を指定せずに作成したセッションは、終了時に自動的に切断されます。 attach_session で接続したセッションは外部で管理され、デフォルトで切断されます。MCP が既存のリモートセッションを意図的に終了する場合に限り、detach: false を渡してください。

特に、次のような場合に便利です。

• 手動テストを続けるためにアプリの状態を保持する
• 複数ステップのワークフローをデバッグする（ツール呼び出しの間、セッションを実行したままにする）
• アプリをインストールしたまま現在の状態を維持したいテストシナリオ

スマートな要素検出

• プラットフォーム固有の要素分類：操作可能な要素とレイアウトコンテナーを自動的に識別します
  • Android：Button、EditText、CheckBox と ViewGroup、FrameLayout、ScrollView
  • iOS：Button、TextField、Switch と View、StackView、CollectionView
• 複数のロケーター戦略：各要素について、アクセシビリティ ID、リソース ID、テキスト、XPath、プラットフォーム固有のセレクターを取得できます
• ビューポートフィルタリング：画面内に表示されている要素だけを取得するか、画面外の要素もすべて取得するかを制御します
• レイアウトのデバッグ：UI 階層を把握するために、コンテナー要素を含めるかどうかを指定できます

権限とアラートの自動処理

iOS と Android の両方のセッションで、システムの権限とアラートを自動的に処理できるようになりました。

• autoGrantPermissions（デフォルト：true）：アプリの権限（カメラ、位置情報など）を自動的に許可します
• autoAcceptAlerts（デフォルト：true）：システムのアラートとダイアログを自動的に受け入れます
• autoDismissAlerts（オプション）：true に設定すると、アラートを受け入れる代わりに閉じます

これにより、自動テスト中に権限のポップアップを手動で処理する必要がなくなります。

技術的な詳細

• 構築技術： TypeScript、WebDriverIO、Appium
• ブラウザーのサポート： Chrome、Firefox、Edge（ヘッドあり／ヘッドレス、自動ドライバー管理）、Safari（ヘッドありのみ、macOS）
• モバイルのサポート： iOS（XCUITest）および Android（UiAutomator2/Espresso）
• プロトコル： Claude Desktop との統合に Model Context Protocol（MCP）を使用
• セッションモデル： アクティブなセッションは単一（ブラウザーまたはモバイルアプリ）
• データ形式： LLM との効率的な通信に TOON（Token-Oriented Object Notation）を使用
• 要素の検出： インテリジェントなフィルタリングと複数の戦略によるロケーター生成を備えた、XML ベースのページソース解析

セッションの記録とコードのエクスポート

すべてのツール呼び出しは、セッション履歴に自動的に記録されます。セッションを調べたり、実行可能なコードをエクスポートしたりするには、MCP リソースを使用します。追加のツール呼び出しは不要です。

• wdio://sessions — 種類、タイムスタンプ、ステップ数を含む、記録済みセッションの一覧
• wdio://session/current/steps — アクティブなセッションのステップログ
• wdio://session/current/code — アクティブなセッション用に生成された実行可能な WebdriverIO JS
• wdio://session/{sessionId}/steps — ID を指定した過去のセッションのステップログ
• wdio://session/{sessionId}/code — ID を指定した過去のセッション用に生成された JS

生成されるスクリプトは、capabilities、ナビゲーション、クリック、入力を含むセッション全体を、単独で実行可能な import { remote } from 'webdriverio' ファイルとして再構築します。クラウドプロバイダーのセッションでは、プロバイダーの REST API を通じてセッション結果を自動的に記録する、完全な try/catch/finally も含まれます。

トレースの記録

start_session に trace: true を渡すと、セッション終了時に .trace/ ディレクトリに Playwright 互換の .trace zip が生成されます。この zip は player.vibium.dev で再生でき、スクリーンショットのフィルムストリップとアクションのタイムラインが表示されます。

スクリーンショットのタイミング

ローカルエミュレーターでは、Appium の takeScreenshot の往復に 700～1300 ms かかります。これは、直前のアクションのアニメーションが落ち着くのに十分な時間です。この特性を利用し、各スクリーンショットは次のアクションが実行される前にキャプチャされるため、Appium サーバーから返される画像には、直前のアクションの結果がすでに反映されています。

難しいのは、トレースプレーヤーでスクリーンショットを正しいアクションの下に表示することです。プレーヤーは、screencast-frame イベントの timestamp フィールドが時刻の範囲内にあるアクションに、そのイベントを関連付けます。タイムスタンプを「現在」（キャプチャ時刻）に設定すると、現在のアクションの startTime より前になり、プレーヤーはその画像を次のアクションの「実行前」の状態としてラベル付けします。つまり、アクションと画像が 1 つずれます。

これを解決するため、各 screencast-frame に lastAfterEndTime（直前に完了したアクションの endTime）を設定します。これにより、画像が前のアクションの時間範囲内に配置され、プレーヤーは次のアクションの前段階ではなく、そのアクションの結果として表示します。

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

セッション終了時の最後のスクリーンショットには、最後のアクションの endTime が設定されます。そのため、タイムライン終了後に孤立したフレームとして表示されるのではなく、そのアクションの下に表示されます。

セッションログ

wdio://session/current/logs リソースは、クラッシュレポート、コンソールエラー、システムログを現在のセッションから取得します。セッションの種類を自動検出し、適切なログバッファーを取得します。

注： このリソースを読み取ると、ログバッファーがクリアされます（WebDriver 仕様に準拠）。次回以降の読み取りでは、前回の読み取り以降に蓄積されたエントリーのみが返されます。ブラウザーログには Chromium（Chrome／Edge）が必要です。Firefox と Safari は getLogs コマンドをサポートしていません。

レスポンスは JSON で、sessionType、logTypes（利用可能なログタイプ）、entries が含まれます。各エントリーには level、message、timestamp（Unix ミリ秒）、timestampISO が含まれます。

トラブルシューティング

ブラウザーの自動化が動作しませんか？

• Chrome、Firefox、Edge、または Safari がインストールされていることを確認してください（Safari には macOS が必要です）
• Claude Desktop を完全に終了してから再起動してみてください
• 他の WebDriver インスタンスが実行されていないことを確認してください

モバイルの自動化が動作しませんか？

• Appium サーバーが実行中であることを確認してください：appium
• デバイス／エミュレーターが実行中であることを確認してください：adb devices（Android）または Xcode Devices（iOS）
• 正しいプラットフォームドライバーがインストールされていることを確認してください
• アプリのパスが正しく、アクセス可能であることを確認してください

問題や改善案がありますか？ ぜひフィードバックをお寄せください！