WebDriverIO
Automatiza navegadores web usando WebDriverIO. Soporta acciones como hacer clic, llenar formularios y tomar capturas de pantalla.
Documentación
Servidor MCP de WebDriverIO
⚠️ Proyecto Archivado
Este proyecto ya no está en desarrollo activo. El servidor MCP oficial de WebDriverIO ahora está disponible como @wdio/mcp, que fue construido usando este proyecto como base.
👉 Usa el paquete oficial en su lugar: https://github.com/webdriverio/mcp
Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a Claude Desktop interactuar con navegadores web y aplicaciones móviles usando WebDriverIO. Automatiza navegadores Chrome, aplicaciones iOS y aplicaciones Android, todo a través de una interfaz unificada.
Características
Automatización de Navegador
- Gestión de Sesiones: Inicia y cierra sesiones de navegador Chrome con modos headless/headed
- Navegación e Interacción: Navega URLs, haz clic en elementos, completa formularios y recupera contenido
- Análisis de Página: Obtén elementos visibles, árboles de accesibilidad, toma capturas de pantalla
- Gestión de Cookies: Obtén, establece y elimina cookies
- Desplazamiento: Desplazamiento suave con distancias configurables
Automatización de Aplicaciones Móviles (iOS/Android)
- Pruebas de Apps Nativas: Prueba apps iOS (.app/.ipa) y Android (.apk) vía Appium
- Gestos Táctiles: Toca, desliza, mantén presionado, arrastra y suelta
- Ciclo de Vida de la App: Inicia, pasa a segundo plano, termina, verifica el estado de la app
- Cambio de Contexto: Cambia sin problemas entre contextos nativos y webview para apps híbridas
- Control de Dispositivo: Rota, bloquea/desbloquea, geolocalización, control de teclado, notificaciones
- Selectores Multiplataforma: IDs de accesibilidad, XPath, UiAutomator (Android), Predicados (iOS)
Herramientas Disponibles
Gestión de Sesiones
| Herramienta | Descripción |
|---|---|
start_browser | Inicia una sesión de navegador Chrome (headless/headed, dimensiones personalizadas) |
start_app_session | Inicia una sesión de app iOS o Android vía Appium (soporta preservación de estado vía noReset) |
close_session | Cierra o se desconecta de la sesión actual de navegador o app (soporta modo detach) |
Navegación e Interacción con la Página (Web y Móvil)
| Herramienta | Descripción |
|---|---|
navigate | Navega a una URL |
get_visible_elements | Obtén elementos visibles e interactuables en la página. Soporta inViewportOnly (predeterminado: true) para filtrar elementos del viewport, y includeContainers (predeterminado: false) para incluir contenedores de diseño en móvil |
get_accessibility | Obtén el árbol de accesibilidad con información semántica de elementos |
scroll_down | Desplázate hacia abajo por píxeles especificados |
scroll_up | Desplázate hacia arriba por píxeles especificados |
take_screenshot | Captura una captura de pantalla |
Interacción con Elementos (Web y Móvil)
| Herramienta | Descripción |
|---|---|
find_element | Encuentra un elemento usando selectores CSS, XPath o selectores móviles |
click_element | Haz clic en un elemento |
click_via_text | Haz clic en un elemento por contenido de texto |
set_value | Escribe texto en campos de entrada |
get_element_text | Obtén el contenido de texto de un elemento |
is_displayed | Verifica si un elemento está visible |
Gestión de Cookies (Web)
| Herramienta | Descripción |
|---|---|
get_cookies | Obtén todas las cookies o una cookie específica por nombre |
set_cookie | Establece una cookie con nombre, valor y atributos opcionales |
delete_cookies | Elimina todas las cookies o una cookie específica |
Gestos Móviles (iOS/Android)
| Herramienta | Descripción |
|---|---|
tap_element | Toca un elemento por selector o coordenadas |
swipe | Desliza en una dirección (arriba/abajo/izquierda/derecha) |
long_press | Mantén presionado un elemento o coordenadas |
drag_and_drop | Arrastra de una ubicación a otra |
Ciclo de Vida de la App (iOS/Android)
| Herramienta | Descripción |
|---|---|
get_app_state | Verifica el estado de la app (instalada, ejecutándose, en segundo plano, en primer plano) |
activate_app | Trae la app al primer plano |
terminate_app | Termina una app en ejecución |
Cambio de Contexto (Apps Híbridas)
| Herramienta | Descripción |
|---|---|
get_contexts | Lista los contextos disponibles (NATIVE_APP, WEBVIEW_*) |
get_current_context | Muestra el contexto actualmente activo |
switch_context | Cambia entre contextos nativos y webview |
Control de Dispositivo (iOS/Android)
| Herramienta | Descripción |
|---|---|
get_device_info | Obtén la plataforma del dispositivo, versión, tamaño de pantalla |
rotate_device | Rota a orientación vertical u horizontal |
get_orientation | Obtén la orientación actual del dispositivo |
lock_device / unlock_device | Bloquea o desbloquea la pantalla del dispositivo |
is_device_locked | Verifica si el dispositivo está bloqueado |
shake_device | Agita el dispositivo (solo iOS) |
send_keys | Envía entrada de teclado (solo Android) |
press_key_code | Presiona código de tecla de Android (BACK=4, HOME=3, etc.) |
hide_keyboard / is_keyboard_shown | Controla el teclado en pantalla |
open_notifications | Abre el panel de notificaciones (solo Android) |
get_geolocation / set_geolocation | Obtén o establece la ubicación GPS del dispositivo |
Instalación y Configuración
Requisitos Previos
Para Automatización de Navegador:
- Node.js (versión 18 o superior)
- Aplicación Claude Desktop
- Navegador Chrome (gestionado automáticamente por WebDriverIO)
Para Automatización de Apps Móviles (Opcional):
- Servidor Appium: Instala 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)
- iOS:
- 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 del dispositivo (Identificador Único de 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 → App de iTunes o Apple Devices → Haz clic en el ícono del dispositivo → Haz clic en "Número de serie" para revelar el UDID
- Método con Xcode: Ventana → Dispositivos y Simuladores → Selecciona el dispositivo → El UDID se muestra como "Identificador"
Instalación
-
Configura Claude Desktop: Agrega la siguiente configuración a la configuración MCP de tu Claude Desktop:
{ "mcpServers": { "webdriverio-mcp": { "command": "npx", "args": ["-y", "webdriverio-mcp"] } }, "globalShortcut": "" }📖 ¿Necesitas ayuda con la configuración de MCP? Lee la guía oficial de configuración de MCP
-
Reinicia Claude Desktop: ⚠️ Importante: Es posible que necesites reiniciar completamente Claude Desktop. En Windows, usa el Administrador de tareas para asegurarte de que esté completamente cerrado antes de reiniciar.
-
Para Automatización Móvil (Opcional): Inicia el servidor Appium antes de usar funciones móviles:
appium # Server runs at http://127.0.0.1:4723 by default
Ejemplos de Uso
Casos de Prueba del Mundo Real
Ejemplo 1: Probando App 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: Probando el 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_browser()
// Headless mode
start_browser({ headless: true })
// Custom dimensions
start_browser({ windowWidth: 1920, windowHeight: 1080 })
// Headless with custom dimensions
start_browser({ headless: true, windowWidth: 1920, windowHeight: 1080 })
Automatización de Apps Móviles
Probando una app 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
Preservando el estado de la app 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)
Probando una app 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
Probando una app 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
Pruebas de apps híbridas (cambiando 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 app) puede estar activa a la vez
- Siempre cierra las sesiones cuando termines para liberar recursos del sistema
- Para cambiar entre navegador y móvil, cierra la sesión actual primero
- Usa
close_session({ detach: true })para desconectarte sin terminar la sesión en el servidor Appium - La preservación de estado se puede controlar con los parámetros
noResetyfullResetdurante la creación de la sesión - Las sesiones creadas con
noReset: trueo sinappPathse desconectarán automáticamente al cerrar
⚠️ Planificación de Tareas:
- Divide 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 Appium debe estar ejecutándose antes de iniciar sesiones móviles
- Asegúrate de que los emuladores/simuladores estén ejecutándose 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) - Android UiAutomator:
android=new UiSelector().text("Login") - Predicado iOS:
-ios predicate string:label == "Login" AND visible == 1 - XPath:
//android.widget.Button[@text="Login"]
Características Avanzadas
Preservación del Estado de la App
Preservación de Estado con noReset/fullReset:
Controla el estado de la app al crear nuevas sesiones usando los parámetros noReset y fullReset:
| noReset | fullReset | Comportamiento |
|---|---|---|
true | false | Preservar estado: La app permanece instalada, los datos se preservan |
false | false | Borrar datos de la app pero mantenerla instalada (predeterminado) |
false | true | Restablecimiento completo: Desinstalar y reinstalar la app (estado limpio) |
| Ejemplo con preservación de estado: |
// Preserve login state between test runs
start_app_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
})
// App launches with existing user data, login tokens, preferences intact
Desconexión de sesiones:
La herramienta close_session admite un parámetro detach que desconecta de la sesión sin terminarla en el servidor de Appium:
// Detach without killing the session
close_session({ detach: true })
// Standard session termination (closes the app and removes session)
close_session({ detach: false }) // or just close_session()
Las sesiones creadas con noReset: true o sin appPath se desconectarán automáticamente al cerrarse.
Esto es particularmente útil cuando:
- Se desea preservar el estado de la aplicación para continuar pruebas manuales
- Se depuran flujos de trabajo de varios pasos (dejar la sesión activa 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: Opcionalmente incluye 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 aplicación (cámara, ubicación, etc.)autoAcceptAlerts(predeterminado: true): Acepta automáticamente alertas y diálogos del sistemaautoDismissAlerts(opcional): Establézcalo 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 navegador: Chrome (con interfaz/sin interfaz, gestión automatizada de controladores)
- Soporte móvil: iOS (XCUITest) y Android (UiAutomator2/Espresso)
- Protocolo: Model Context Protocol (MCP) para 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 comunicación eficiente con LLM
- Detección de elementos: Análisis de código fuente de página basado en XML con filtrado inteligente y generación de localizadores de múltiples estrategias
Solución de problemas
¿La automatización del navegador no funciona?
- Asegúrese de que Chrome esté instalado
- Intente reiniciar Claude Desktop por completo
- Verifique que no haya otras instancias de WebDriver en ejecución
¿La automatización móvil no funciona?
- Verifique que el servidor de Appium esté en ejecución:
appium - Compruebe que el dispositivo/emulador esté en ejecución:
adb devices(Android) o Xcode Devices (iOS) - Asegúrese de que los controladores de plataforma correctos estén instalados
- Verifique que la ruta de la aplicación sea correcta y accesible
¿Encontró problemas o tiene sugerencias? ¡Comparta sus comentarios!