WebDriverIO

Servidor MCP WebDriverIO

⚠️ Projeto Arquivado

Este projeto não está mais em desenvolvimento ativo. O servidor MCP oficial do WebDriverIO agora está disponível como @wdio/mcp, que foi construído usando este projeto como base.

👉 Use o pacote oficial em vez disso: https://github.com/webdriverio/mcp

Um servidor Model Context Protocol (MCP) que permite ao Claude Desktop interagir com navegadores web e aplicativos móveis usando WebDriverIO. Automatize navegadores Chrome, aplicativos iOS e aplicativos Android—tudo através de uma interface unificada.

Recursos

Automação de Navegador

• Gerenciamento de Sessão: Inicie e feche sessões do navegador Chrome com modos headless/headed
• Navegação e Interação: Navegue por URLs, clique em elementos, preencha formulários e recupere conteúdo
• Análise de Página: Obtenha elementos visíveis, árvores de acessibilidade, tire capturas de tela
• Gerenciamento de Cookies: Obtenha, defina e exclua cookies
• Rolagem: Rolagem suave com distâncias configuráveis

Automação de Aplicativos Móveis (iOS/Android)

• Teste de Aplicativos Nativos: Teste aplicativos iOS (.app/.ipa) e Android (.apk) via Appium
• Gestos de Toque: Toque, deslize, pressione e segure, arraste e solte
• Ciclo de Vida do Aplicativo: Inicie, coloque em segundo plano, encerre, verifique o estado do aplicativo
• Alternância de Contexto: Alterne perfeitamente entre contextos nativos e webview para aplicativos híbridos
• Controle de Dispositivo: Gire, bloqueie/desbloqueie, geolocalização, controle de teclado, notificações
• Seletores Multiplataforma: IDs de acessibilidade, XPath, UiAutomator (Android), Predicados (iOS)

Ferramentas Disponíveis

Gerenciamento de Sessão

Ferramenta	Descrição
start_browser	Inicie uma sessão do navegador Chrome (headless/headed, dimensões personalizadas)
start_app_session	Inicie uma sessão de aplicativo iOS ou Android via Appium (suporta preservação de estado via noReset)
close_session	Feche ou desconecte da sessão atual do navegador ou aplicativo (suporta modo detach)

Navegação e Interação com Página (Web e Móvel)

Ferramenta	Descrição
navigate	Navegue para uma URL
get_visible_elements	Obtenha elementos visíveis e interativos na página. Suporta inViewportOnly (padrão: true) para filtrar elementos do viewport e includeContainers (padrão: false) para incluir contêineres de layout em dispositivos móveis
get_accessibility	Obtenha a árvore de acessibilidade com informações semânticas dos elementos
scroll_down	Role para baixo por pixels especificados
scroll_up	Role para cima por pixels especificados
take_screenshot	Capture uma captura de tela

Interação com Elementos (Web e Móvel)

Ferramenta	Descrição
find_element	Encontre um elemento usando seletores CSS, XPath ou seletores móveis
click_element	Clique em um elemento
click_via_text	Clique em um elemento pelo conteúdo do texto
set_value	Digite texto em campos de entrada
get_element_text	Obtenha o conteúdo de texto de um elemento
is_displayed	Verifique se um elemento está exibido

Gerenciamento de Cookies (Web)

Ferramenta	Descrição
get_cookies	Obtenha todos os cookies ou um cookie específico pelo nome
set_cookie	Defina um cookie com nome, valor e atributos opcionais
delete_cookies	Exclua todos os cookies ou um cookie específico

Gestos Móveis (iOS/Android)

Ferramenta	Descrição
tap_element	Toque em um elemento por seletor ou coordenadas
swipe	Deslize em uma direção (cima/baixo/esquerda/direita)
long_press	Pressione e segure um elemento ou coordenadas
drag_and_drop	Arraste de um local para outro

Ciclo de Vida do Aplicativo (iOS/Android)

Ferramenta	Descrição
get_app_state	Verifique o estado do aplicativo (instalado, em execução, em segundo plano, em primeiro plano)
activate_app	Traga o aplicativo para o primeiro plano
terminate_app	Encerre um aplicativo em execução

Alternância de Contexto (Aplicativos Híbridos)

Ferramenta	Descrição
get_contexts	Liste os contextos disponíveis (NATIVE_APP, WEBVIEW_*)
get_current_context	Mostre o contexto atualmente ativo
switch_context	Alterne entre contextos nativos e webview

Controle de Dispositivo (iOS/Android)

Ferramenta	Descrição
get_device_info	Obtenha plataforma do dispositivo, versão, tamanho da tela
rotate_device	Gire para orientação retrato ou paisagem
get_orientation	Obtenha a orientação atual do dispositivo
lock_device / unlock_device	Bloqueie ou desbloqueie a tela do dispositivo
is_device_locked	Verifique se o dispositivo está bloqueado
shake_device	Agite o dispositivo (somente iOS)
send_keys	Envie entrada de teclado (somente Android)
press_key_code	Pressione código de tecla Android (BACK=4, HOME=3, etc.)
hide_keyboard / is_keyboard_shown	Controle o teclado na tela
open_notifications	Abra o painel de notificações (somente Android)
get_geolocation / set_geolocation	Obtenha ou defina a localização GPS do dispositivo

Instalação e Configuração

Pré-requisitos

Para Automação de Navegador:

• Node.js (versão 18 ou superior)
• Aplicativo Claude Desktop
• Navegador Chrome (gerenciado automaticamente pelo WebDriverIO)

Para Automação de Aplicativos Móveis (Opcional):

• Servidor Appium: Instale globalmente com npm install -g appium
• Drivers de Plataforma:
  • iOS: appium driver install xcuitest (requer Xcode no macOS)
  • Android: appium driver install uiautomator2 (requer Android Studio)
• Dispositivos/Emuladores:
  • Simulador iOS (macOS) ou dispositivo físico
  • Emulador Android ou dispositivo físico
• Para Dispositivos iOS Reais: Você precisará do UDID do dispositivo (Identificador Único de Dispositivo)
  • Encontre o UDID no macOS: Conecte o dispositivo → Abra o Finder → Selecione o dispositivo → Clique no nome/modelo do dispositivo para revelar o UDID
  • Encontre o UDID no Windows: Conecte o dispositivo → Aplicativo iTunes ou Apple Devices → Clique no ícone do dispositivo → Clique em "Número de Série" para revelar o UDID
  • Método Xcode: Janela → Dispositivos e Simuladores → Selecione o dispositivo → UDID mostrado como "Identificador"

Instalação

1. Configure o Claude Desktop: Adicione a seguinte configuração às configurações MCP do seu Claude Desktop:

   {
     "mcpServers": {
       "webdriverio-mcp": {
         "command": "npx",
         "args": ["-y", "webdriverio-mcp"]
       }
     },
     "globalShortcut": ""
   }
   

   📖 Precisa de ajuda com a configuração do MCP? Leia o guia oficial de configuração do MCP

2. Reinicie o Claude Desktop: ⚠️ Importante: Você pode precisar reiniciar completamente o Claude Desktop. No Windows, use o Gerenciador de Tarefas para garantir que ele esteja completamente fechado antes de reiniciar.

3. Para Automação Móvel (Opcional): Inicie o servidor Appium antes de usar recursos móveis:

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

Exemplos de Uso

Casos de Teste do Mundo Real

Exemplo 1: Testando Aplicativo Android de Demonstração (Digitalização de Livros)

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

Exemplo 2: Testando o Site de Comércio Eletrô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

Automação de Navegador

Prompt básico de teste 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

Opções de configuração do 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 })

Automação de Aplicativos Móveis

Testando um aplicativo iOS no 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 o estado do aplicativo entre sessões:

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)

Testando um aplicativo iOS em 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

Testando um aplicativo 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

Detecção avançada 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

Teste de aplicativo híbrido (alternando 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

⚠️ Gerenciamento de Sessão:

• Apenas uma sessão (navegador OU aplicativo) pode estar ativa por vez
• Sempre feche as sessões quando terminar para liberar recursos do sistema
• Para alternar entre navegador e móvel, feche a sessão atual primeiro
• Use close_session({ detach: true }) para desconectar sem encerrar a sessão no servidor Appium
• Preservação de estado pode ser controlada com os parâmetros noReset e fullReset durante a criação da sessão
• Sessões criadas com noReset: true ou sem appPath serão desconectadas automaticamente ao fechar

⚠️ Planejamento de Tarefas:

• Divida automações complexas em operações menores e focadas
• O Claude pode consumir rapidamente os limites de mensagens com automação extensa

⚠️ Automação Móvel:

• O servidor Appium deve estar em execução antes de iniciar sessões móveis
• Certifique-se de que emuladores/simuladores estejam em execução e dispositivos estejam conectados
• A automação iOS requer macOS com Xcode instalado
• Dispositivos iOS Reais: Testar em dispositivos iOS físicos requer o UDID do dispositivo (identificador único de 40 caracteres). Consulte a seção Pré-requisitos para saber como encontrar seu UDID

Referência Rápida de Sintaxe de Seletores

Web (CSS/XPath):

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

Móvel (Multiplataforma):

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

Recursos Avançados

Preservação de Estado do Aplicativo

Preservação de Estado com noReset/fullReset: Controle o estado do aplicativo ao criar novas sessões usando os parâmetros noReset e fullReset:

noReset	fullReset	Comportamento
true	false	Preservar estado: O aplicativo permanece instalado, dados preservados
false	false	Limpar dados do aplicativo, mas manter o aplicativo instalado (padrão)
false	true	Reset completo: Desinstalar e reinstalar o aplicativo (estado limpo)
Exemplo com preservação 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

Desanexar de Sessões: A ferramenta close_session suporta um parâmetro detach que desconecta da sessão sem encerrá-la no servidor 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()

Sessões criadas com noReset: true ou sem appPath serão desanexadas automaticamente ao fechar.

Isso é particularmente útil quando:

• Preservar o estado do aplicativo para continuar testes manuais
• Depurar fluxos de trabalho de várias etapas (deixar a sessão em execução entre invocações de ferramentas)
• Testar cenários em que você deseja que o aplicativo permaneça instalado e no estado atual

Detecção Inteligente de Elementos

• Classificação de elementos específica da plataforma: Identifica automaticamente elementos interativos versus contêineres de layout
  • Android: Button, EditText, CheckBox versus ViewGroup, FrameLayout, ScrollView
  • iOS: Button, TextField, Switch versus View, StackView, CollectionView
• Múltiplas estratégias de localização: Cada elemento fornece ID de acessibilidade, ID de recurso, texto, XPath e seletores específicos da plataforma
• Filtragem por viewport: Controla se deseja obter apenas elementos visíveis ou todos os elementos, incluindo os fora da tela
• Depuração de layout: Opcionalmente inclui elementos contêineres para entender a hierarquia da interface

Tratamento Automático de Permissões e Alertas

Sessões iOS e Android agora suportam tratamento automático de permissões e alertas do sistema:

• autoGrantPermissions (padrão: true): Concede automaticamente permissões de aplicativos (câmera, localização, etc.)
• autoAcceptAlerts (padrão: true): Aceita automaticamente alertas e diálogos do sistema
• autoDismissAlerts (opcional): Defina como true para dispensar alertas em vez de aceitá-los

Isso elimina a necessidade de lidar manualmente com pop-ups de permissão durante testes automatizados.

Detalhes Técnicos

• Construído com: TypeScript, WebDriverIO, Appium
• Suporte a Navegadores: Chrome (com interface/sem interface, gerenciamento automatizado de drivers)
• Suporte a Dispositivos Móveis: iOS (XCUITest) e Android (UiAutomator2/Espresso)
• Protocolo: Model Context Protocol (MCP) para integração com Claude Desktop
• Modelo de Sessão: Sessão ativa única (navegador ou aplicativo móvel)
• Formato de Dados: TOON (Token-Oriented Object Notation) para comunicação eficiente com LLM
• Detecção de Elementos: Análise de fonte de página baseada em XML com filtragem inteligente e geração de localizadores com múltiplas estratégias

Solução de Problemas

Automação de navegador não está funcionando?

• Certifique-se de que o Chrome está instalado
• Tente reiniciar o Claude Desktop completamente
• Verifique se não há outras instâncias do WebDriver em execução

Automação móvel não está funcionando?

• Verifique se o servidor Appium está em execução: appium
• Verifique se o dispositivo/emulador está em execução: adb devices (Android) ou Xcode Devices (iOS)
• Certifique-se de que os drivers de plataforma corretos estão instalados
• Verifique se o caminho do aplicativo está correto e acessível

Encontrou problemas ou tem sugestões? Compartilhe seu feedback!