WebdriverIO MCP

Servidor MCP de WebDriverIO

Un servidor de Model Context Protocol (MCP) que permite a los asistentes de IA interactuar con navegadores web y aplicaciones móviles usando WebDriverIO. Automatiza los navegadores Chrome, Firefox, Edge y Safari, además de aplicaciones iOS y Android, todo a través de una interfaz unificada.

Instalación

Añade la siguiente configuración a los ajustes de tu cliente MCP:

Configuración estándar (funciona en la mayoría de los clientes):

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

⚠️ Reinicio requerido: Después de añadir la configuración, reinicia completamente tu cliente MCP para aplicar los cambios.

Opción 2: Instalación global

Si prefieres instalar globalmente:

npm install -g @wdio/mcp

Luego usa wdio-mcp como comando:

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

📖 ¿Necesitas ayuda? Sigue la guía de instalación de MCP.

Transporte HTTP (para clientes que no usan subprocesos)

Por defecto, el servidor usa transporte stdio (subproceso). Para clientes que no pueden lanzar subprocesos (p. ej. llama.cpp, modo seguro de OpenAI Codex), habilita el transporte HTTP:

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

Luego apunta tu cliente MCP a http://localhost:3000/mcp.

Requisitos previos para la automatización de aplicaciones móviles

• Servidor Appium: Instálalo globalmente con npm install -g appium
• Controladores de plataforma:
  • iOS: appium driver install xcuitest (requiere Xcode en macOS)
  • Android: appium driver install uiautomator2 (requiere Android Studio)
• Dispositivos/Emuladores:
  • Simulador de iOS (macOS) o dispositivo físico
  • Emulador de Android o dispositivo físico
• Para dispositivos iOS reales: Necesitarás el UDID (Identificador Único de Dispositivo) del dispositivo
  • Encuentra el UDID en macOS: Conecta el dispositivo → Abre Finder → Selecciona el dispositivo → Haz clic en el nombre/modelo del dispositivo para revelar el UDID
  • Encuentra el UDID en Windows: Conecta el dispositivo → iTunes o la app Apple Devices → Haz clic en el icono del dispositivo → Haz clic en "Número de serie" para revelar el UDID
  • Método con Xcode: Ventana → Devices and Simulators → Selecciona el dispositivo → El UDID se muestra como "Identifier"

Inicia el servidor Appium antes de usar las funciones móviles:

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

Proveedores en la nube

Ejecuta pruebas de navegador y aplicaciones móviles en dispositivos y navegadores reales en la nube sin configuración local. Actualmente es compatible con BrowserStack, Sauce Labs, LambdaTest, TestingBot y Digital.ai Testing.

Requisitos previos

Establece las credenciales de tu proveedor como variables de entorno o en la configuración de tu cliente 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 }
})

Sesiones de navegador

Ejecuta un navegador en una combinación específica de SO/versión:

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

Comportamiento específico de os / osVersion por proveedor:

• BrowserStack — os y osVersion se asignan a campos bstack:options.os / bstack:options.osVersion separados.
• Sauce Labs / LambdaTest / TestingBot — os y osVersion se combinan en la capacidad W3C platformName (p. ej., os: 'Windows' + osVersion: '11' → platformName: 'Windows 11'). Estos proveedores usan valores platformName como "Windows 11", "MacOS Sequoia" o "Linux". TestingBot usa Windows 11 por defecto cuando se omite os.
• Digital.ai — os y osVersion se combinan en la capacidad plana digitalai:osName (NO platformName), p. ej. os: 'Windows' + osVersion: '11' → digitalai:osName: 'Windows 11'.

Sesiones de aplicaciones móviles

Prueba en dispositivos reales en la nube. Primero sube tu aplicación (o usa una URL de aplicación existente):

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

Sesiones de navegador móvil

Ejecuta un navegador en un dispositivo móvil en la nube (dispositivo real o emulador/simulador) sin subir una aplicación:

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

Nota: Las sesiones de navegador móvil no requieren app, appPath ni noReset. El proveedor lanza un navegador directamente en el dispositivo seleccionado, ya sea real o emulador/simulador.

Usa list_apps para ver las aplicaciones subidas anteriormente:

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

Túnel local

Para probar contra URLs que solo son accesibles en tu máquina local o red interna, habilita un túnel local:

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

El parámetro tunnel reemplaza los parámetros obsoletos browserstackLocal, saucelabsLocal y testmuLocal. Establécelo en true para iniciar el túnel automáticamente (se detiene automáticamente después de la sesión), o en 'external' para usar un túnel que ya se esté ejecutando en tu máquina.

Nota: Con tunnel: true, el proveedor descarga y gestiona el binario del túnel por ti. Para tunnel: 'external', lo ejecutas tú mismo: los recursos wdio://saucelabs/local-binary, wdio://testmu/local-binary y wdio://testingbot/local-binary proporcionan URLs de descarga e instrucciones de configuración. El túnel de TestingBot es un único JAR de Java multiplataforma (requiere Java 11+) en lugar de un binario por plataforma.

Etiquetas de informes

Todos los tipos de sesión admiten etiquetas reporting que aparecen en el panel del proveedor:

Herramientas de proveedores en la nube

Ambas herramientas requieren un parámetro provider ('browserstack', 'saucelabs', 'testmu', 'testingbot' o 'digitalai').

Características

Automatización de navegador

• Gestión de sesiones: Inicia y cierra sesiones de navegador (Chrome, Firefox, Edge, Safari) con modos headless/con ventana
• Navegación e interacción: Navega por URLs, haz clic en elementos, rellena formularios y recupera contenido
• Análisis de página: Obtén elementos visibles, árboles de accesibilidad, capturas de pantalla
• Gestión de cookies: Obtén, establece y elimina cookies
• Desplazamiento: Desplazamiento suave con distancias configurables
• Adjuntar a Chrome en ejecución: Conéctate a una ventana de Chrome existente mediante --remote-debugging-port — ideal para probar sesiones autenticadas o preconfiguradas
• Conectar a endpoints WebDriver existentes: Reutiliza un endpoint WebDriver compatible con Selenium ya en ejecución, como un navegador gestionado por un framework o un puente de automatización de webview de escritorio (como Tauri)
• Emulación de dispositivos: Aplica ajustes preestablecidos de móvil/tableta (iPhone 15, Pixel 7, etc.) para simular diseños responsivos sin un dispositivo físico
• Grabación de sesiones: Todas las llamadas a herramientas se graban automáticamente y se pueden exportar como JS de WebdriverIO ejecutable

Automatización de aplicaciones móviles (iOS/Android)

• Pruebas de aplicaciones nativas: Prueba aplicaciones de Android (.apk) e iOS (.app/.ipa) mediante Appium
• Gestos táctiles: Tocar, deslizar, mantener pulsado, arrastrar y soltar
• Ciclo de vida de la aplicación: Iniciar, pasar a segundo plano, terminar, comprobar el estado de la aplicación
• Cambio de contexto: Cambia sin problemas entre contextos nativos y webview para aplicaciones híbridas
• Control de dispositivos: Rotar, bloquear/desbloquear, geolocalización, control de teclado, notificaciones
• Selectores multiplataforma: IDs de accesibilidad, XPath, UiAutomator (Android), Predicates (iOS)

Herramientas disponibles

Gestión de sesiones

Navegación e Interacción con la Página (Web y Móvil)

Interacción con Elementos (Web y Móvil)

Gestión de Cookies (Web)

Gestos Móviles (iOS/Android)

Cambio de Contexto (Aplicaciones Híbridas)

Control de Dispositivo (iOS/Android)

Recursos MCP (solo lectura, no se necesita llamada de herramienta)

Ejemplos de Uso

Casos de Prueba del Mundo Real

Ejemplo 1: Prueba de la aplicación Android de demostración (escaneo de libros)

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

Ejemplo 2: Prueba del sitio de comercio electrónico World of Books

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

Automatización de Navegador

Solicitud básica de prueba 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

Opciones de configuración del navegador:

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

Adjuntarse a una instancia de Chrome en ejecución:

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

Conectarse a un endpoint de WebDriver existente:

Use provider: 'external' cuando otro proceso ya posee el ciclo de vida del navegador o webview y expone un endpoint W3C WebDriver. Esto es útil para sesiones de Selenium Grid, controladores de navegador gestionados externamente, o aplicaciones de escritorio como aplicaciones Tauri que incorporan un webview y exponen WebDriver por separado. El servidor MCP se conecta al endpoint; no inicia ni detiene la aplicación de destino, no inicia túneles ni gestiona la configuración específica del framework.

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

Para aplicaciones de escritorio con webview como Tauri, primero inicie la aplicación y su puente WebDriver fuera de este servidor MCP, luego pase el endpoint y las capacidades requeridas. Por ejemplo, un puente WebDriver de Tauri puede requerir capabilities: {browserName: 'tauri'}.

Adjuntarse a una sesión existente de WebDriver o Appium:

Use attach_session cuando la sesión ya haya sido creada por otro proceso. El MCP reutiliza el endpoint y las credenciales del proveedor seleccionado, registra el conjunto de comandos de navegador/móvil apropiado localmente y no emite una solicitud de nueva sesión. Las sesiones adjuntas se gestionan externamente: close_session() se desconecta de forma predeterminada, mientras que close_session({detach: false}) termina explícitamente la sesión remota.

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

Una sesión en la nube existente debe seguir usando el túnel con el que fue creada. attach_session nunca inicia ni detiene un túnel, así que mantenga el proceso del túnel original activo durante todo el tiempo que la sesión lo necesite.

Emulación de dispositivo (requiere sesión 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

Extensiones web (requiere sesión 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'
})

Automatización de Aplicaciones Móviles

Prueba de una aplicación iOS en simulador:

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

Preservación del estado de la aplicación entre sesiones:

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)

Prueba de una aplicación iOS en dispositivo real:

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

Prueba de una aplicación 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

Detección avanzada de elementos:

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

Prueba de aplicaciones híbridas (cambio de contextos):

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

Notas Importantes

⚠️ Gestión de Sesiones:

• Solo una sesión (navegador O aplicación) puede estar activa a la vez
• Cierre siempre las sesiones al terminar para liberar recursos del sistema
• Para cambiar entre navegador y móvil, cierre primero la sesión actual
• Use close_session({ detach: true }) para desconectarse sin terminar la sesión en el servidor de Appium
• La preservación del estado se puede controlar con los parámetros noReset y fullReset durante la creación de la sesión
• Las sesiones creadas con noReset: true o sin appPath se desconectarán automáticamente al cerrarse
• Las sesiones adoptadas con attach_session siempre se desconectan al cerrarse a menos que detach: false se solicite explícitamente

⚠️ Planificación de Tareas:

• Divida la automatización compleja en operaciones más pequeñas y enfocadas
• Claude puede consumir rápidamente los límites de mensajes con automatización extensa

⚠️ Automatización Móvil:

• El servidor de Appium debe estar en ejecución antes de iniciar sesiones móviles
• Asegúrate de que los emuladores/simuladores estén en ejecución y los dispositivos estén conectados
• La automatización de iOS requiere macOS con Xcode instalado
• Dispositivos iOS reales: Probar en dispositivos iOS físicos requiere el UDID del dispositivo (identificador único de 40 caracteres). Consulta la sección de Requisitos previos para saber cómo encontrar tu UDID

Referencia rápida de sintaxis de selectores

Web (CSS/XPath):

• CSS: button.my-class, #element-id
• XPath: //button[@class='my-class']
• Texto: button=Exact text, a*=Contains text

Móvil (multiplataforma):

• ID de accesibilidad: ~loginButton (funciona tanto en iOS como en Android)
• UiAutomator de Android: android=new UiSelector().text("Login")
• Predicado de iOS: -ios predicate string:label == "Login" AND visible == 1
• XPath: //android.widget.Button[@text="Login"]

Funciones avanzadas

Preservación del estado de la aplicación

Preservación de estado con noReset/fullReset: Controla el estado de la aplicación al crear nuevas sesiones usando los parámetros noReset y fullReset:

Ejemplo con preservación de estado:

// 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

Desconexión de sesiones: La herramienta close_session admite un parámetro detach que se desconecta de la sesión sin terminarla en el servidor de Appium:

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

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

Las sesiones creadas con noReset: true o sin appPath se desconectarán automáticamente al cerrarse. Las sesiones adoptadas con attach_session se gestionan externamente y también se desconectan de forma predeterminada; pasa detach: false solo cuando el MCP deba terminar deliberadamente la sesión remota existente.

Esto es particularmente útil cuando:

• Se preserva el estado de la aplicación para continuar las pruebas manuales
• Se depuran flujos de trabajo de varios pasos (dejar la sesión en ejecución entre invocaciones de herramientas)
• Se prueban escenarios donde se desea que la aplicación permanezca instalada y en su estado actual

Detección inteligente de elementos

• Clasificación de elementos específica de la plataforma: identifica automáticamente elementos interactuables frente a contenedores de diseño
  • Android: Button, EditText, CheckBox frente a ViewGroup, FrameLayout, ScrollView
  • iOS: Button, TextField, Switch frente a View, StackView, CollectionView
• Múltiples estrategias de localización: cada elemento proporciona ID de accesibilidad, ID de recurso, texto, XPath y selectores específicos de la plataforma
• Filtrado por viewport: controla si se obtienen solo elementos visibles o todos los elementos, incluidos los fuera de pantalla
• Depuración de diseño: incluye opcionalmente elementos contenedores para comprender la jerarquía de la interfaz de usuario

Manejo automático de permisos y alertas

Tanto las sesiones de iOS como las de Android ahora admiten el manejo automático de permisos y alertas del sistema:

• autoGrantPermissions (predeterminado: true): otorga automáticamente permisos de la aplicación (cámara, ubicación, etc.)
• autoAcceptAlerts (predeterminado: true): acepta automáticamente alertas y diálogos del sistema
• autoDismissAlerts (opcional): configúralo en true para descartar alertas en lugar de aceptarlas

Esto elimina la necesidad de manejar manualmente las ventanas emergentes de permisos durante las pruebas automatizadas.

Detalles técnicos

• Construido con: TypeScript, WebDriverIO, Appium
• Soporte de navegadores: Chrome, Firefox, Edge (con interfaz/sin interfaz, gestión automatizada de controladores), Safari (solo con interfaz; macOS)
• Soporte móvil: iOS (XCUITest) y Android (UiAutomator2/Espresso)
• Protocolo: Model Context Protocol (MCP) para la integración con Claude Desktop
• Modelo de sesión: sesión activa única (navegador o aplicación móvil)
• Formato de datos: TOON (Token-Oriented Object Notation) para una comunicación eficiente con LLM
• Detección de elementos: análisis de la fuente de la página basado en XML con filtrado inteligente y generación de localizadores de múltiples estrategias

Grabación de sesiones y exportación de código

Cada llamada a una herramienta se registra automáticamente en el historial de la sesión. Puedes inspeccionar las sesiones y exportar código ejecutable a través de los recursos de MCP, sin necesidad de llamadas adicionales a herramientas:

• wdio://sessions — lista todas las sesiones grabadas con tipo, marcas de tiempo y número de pasos
• wdio://session/current/steps — registro de pasos de la sesión activa
• wdio://session/current/code — JS de WebdriverIO ejecutable generado para la sesión activa
• wdio://session/{sessionId}/steps — registro de pasos de cualquier sesión anterior por ID
• wdio://session/{sessionId}/code — JS generado para cualquier sesión anterior por ID

El script generado reconstruye la sesión completa, incluidas las capacidades, la navegación, los clics y las entradas, como un archivo import { remote } from 'webdriverio' independiente. Para sesiones de proveedores en la nube, incluye el bloque try/catch/finally completo con el marcado automático del resultado de la sesión mediante la API REST del proveedor.

Grabación de trazas

Pasar trace: true a start_session produce un zip .trace compatible con Playwright en el directorio .trace/ cuando la sesión se cierra. El zip se puede reproducir en player.vibium.dev y muestra una tira de capturas de pantalla junto con la línea de tiempo de las acciones.

Cómo se temporizan las capturas de pantalla

El viaje de ida y vuelta de takeScreenshot de Appium tarda entre 700 y 1300 ms en un emulador local, lo cual es suficiente para que las animaciones de la acción anterior se asienten. Aprovechamos esto: cada captura de pantalla se toma antes de que se ejecute la siguiente acción, por lo que lo que devuelve el servidor de Appium ya es el resultado asentado de la acción anterior.

La parte complicada es hacer que el reproductor de trazas muestre esa captura de pantalla bajo la acción correcta. El reproductor asocia un evento screencast-frame con la ventana de tiempo de la acción que contiene el campo timestamp del fotograma. Si la marca de tiempo se establece en "ahora" (tiempo de captura), cae antes del startTime de la acción actual y el reproductor la etiqueta como el estado anterior de la siguiente acción, desincronizada en una acción.

La solución: sellar cada screencast-frame con lastAfterEndTime — el endTime de la acción que acaba de completarse. Esto coloca el fotograma dentro de la ventana de la acción anterior, por lo que el reproductor lo muestra como el resultado de esa acción, no como el precursor de la siguiente.

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

La captura de pantalla final al cerrar la sesión se sella con el endTime de la última acción, por lo que se muestra bajo esa acción en lugar de aparecer como un fotograma huérfano después de que termine la línea de tiempo.

Registros de sesión

El recurso wdio://session/current/logs devuelve informes de fallos, errores de consola y registros del sistema para la sesión actual, detectando automáticamente el tipo de sesión para obtener el búfer de registro correcto:

Nota: Leer este recurso limpia el búfer de registro (según la especificación de WebDriver). Las lecturas posteriores devuelven solo las entradas acumuladas desde la última lectura. Los registros del navegador requieren Chromium (Chrome/Edge) — Firefox y Safari no admiten el comando getLogs.

La respuesta es JSON con sessionType, logTypes (tipos de registro disponibles) y entries — cada entrada incluye level, message, timestamp (ms Unix) y timestampISO.

Solución de problemas

¿La automatización del navegador no funciona?

• Asegúrate de que Chrome, Firefox, Edge o Safari estén instalados (Safari requiere macOS)
• Intenta reiniciar Claude Desktop por completo
• Comprueba que no haya otras instancias de WebDriver en ejecución

¿La automatización móvil no funciona?

• Verifica que el servidor de Appium esté en ejecución: appium
• Comprueba que el dispositivo/emulador esté en ejecución: adb devices (Android) o Dispositivos Xcode (iOS)
• Asegúrate de que los controladores de plataforma correctos estén instalados
• Verifica que la ruta de la aplicación sea correcta y accesible

¿Encontraste problemas o tienes sugerencias? ¡Comparte tus comentarios!