Pular para o conteúdo principal

Ferramentas

As seguintes ferramentas estão disponíveis através do servidor WebdriverIO MCP. Essas ferramentas permitem que assistentes de IA automatizem navegadores e aplicativos móveis.

Gerenciamento de Sessão​

start_browser​

Inicia uma sessão de navegador Chrome.

Parâmetros​

ParâmetroTipoObrigatórioPadrãoDescrição
headlessbooleanNãofalseExecutar Chrome em modo headless
windowWidthnumberNão1920Largura da janela do navegador (400-3840)
windowHeightnumberNão1080Altura da janela do navegador (400-2160)
navigationUrlstringNão-URL para navegar após iniciar o navegador

Exemplo​

Start a browser with 1920x1080 resolution and navigate to webdriver.io

Suporte​

  • Navegadores Desktop

start_app_session​

Inicia uma sessão de aplicativo móvel no iOS ou Android via Appium.

Parâmetros​

ParâmetroTipoObrigatórioPadrãoDescrição
platformstringSim-Plataforma para automatizar: iOS ou Android
deviceNamestringSim-Nome do dispositivo ou simulador/emulador
appPathstringNão*-Caminho para o arquivo do aplicativo (.app, .ipa, ou .apk)
platformVersionstringNão-Versão do SO (ex., 17.0, 14)
automationNamestringNãoAutoXCUITest (iOS), UiAutomator2 ou Espresso (Android)
udidstringNão-Identificador único do dispositivo (necessário para dispositivos iOS reais)
noResetbooleanNãofalsePreservar estado do aplicativo entre sessões
fullResetbooleanNãotrueDesinstalar e reinstalar o aplicativo antes da sessão
autoGrantPermissionsbooleanNãotrueConceder permissões do aplicativo automaticamente
autoAcceptAlertsbooleanNãotrueAceitar alertas do sistema automaticamente
autoDismissAlertsbooleanNãofalseDispensar (em vez de aceitar) alertas
appWaitActivitystringNão-Activity para aguardar na inicialização (somente Android)
newCommandTimeoutnumberNão60Segundos antes da sessão expirar devido a inatividade
appiumHoststringNão127.0.0.1Hostname do servidor Appium
appiumPortnumberNão4723Porta do servidor Appium
appiumPathstringNão/Caminho do servidor Appium

*Ou appPath deve ser fornecido, ou noReset: true para conectar a um aplicativo já em execução.

Exemplo​

Start an iOS app session on iPhone 15 simulator with my app at /path/to/app.app

Suporte​

  • Simuladores iOS
  • Dispositivos iOS reais
  • Emuladores Android
  • Dispositivos Android reais

close_session​

Fecha a sessão atual do navegador ou aplicativo.

Parâmetros​

ParâmetroTipoObrigatórioPadrãoDescrição
detachbooleanNãofalseDesanexar da sessão em vez de fechar (mantém o navegador/aplicativo em execução)

Notas​

Sessões com noReset: true ou sem appPath são automaticamente desanexadas ao fechar para preservar o estado.

Suporte​

  • Navegadores Desktop
  • Aplicativos Móveis

Navega para uma URL.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
urlstringSimA URL para navegar

Exemplo​

Navigate to https://webdriver.io

Suporte​

  • Navegadores Desktop

Interação com Elementos​

click_element​

Clica em um elemento identificado por um seletor.

Parâmetros​

ParâmetroTipoObrigatórioPadrãoDescrição
selectorstringSim-Seletor CSS, XPath ou seletor móvel
scrollToViewbooleanNãotrueRolar o elemento para a visualização antes de clicar
timeoutnumberNão3000Tempo máximo para aguardar o elemento (ms)

Notas​

  • Suporta seletores de texto WebdriverIO: button=Texto exato ou a*=Contém texto
  • Usa alinhamento central para posicionamento de rolagem

Exemplo​

Click the element with selector "#submit-button"

Suporte​

  • Navegadores Desktop
  • Aplicativos Nativos Móveis

set_value​

Digita texto em um campo de entrada.

Parâmetros​

ParâmetroTipoObrigatórioPadrãoDescrição
selectorstringSim-Seletor para o elemento de entrada
valuestringSim-Texto para digitar
scrollToViewbooleanNãotrueRolar o elemento para a visualização antes de digitar
timeoutnumberNão3000Tempo máximo para aguardar o elemento (ms)

Notas​

Limpa o valor existente antes de digitar o novo texto.

Exemplo​

Set the value "john@example.com" in the element with selector "#email"

Suporte​

  • Navegadores Desktop
  • Aplicativos Nativos Móveis

Análise de Página​

get_visible_elements​

Obtém elementos visíveis e interativos na página ou tela atual. Esta é a principal ferramenta para descobrir quais elementos estão disponíveis para interação.

Parâmetros​

ParâmetroTipoObrigatórioPadrãoDescrição
elementTypestringNãointeractableTipo de elementos: interactable (botões/links/entradas), visual (imagens/SVGs), ou all
inViewportOnlybooleanNãotrueRetornar apenas elementos visíveis na viewport
includeContainersbooleanNãofalseIncluir contêineres de layout (ViewGroup, ScrollView, etc.)
includeBoundsbooleanNãofalseIncluir coordenadas dos elementos (x, y, width, height)
limitnumberNão0Máximo de elementos a retornar (0 = ilimitado)
offsetnumberNão0Número de elementos a pular (para paginação)

Retorna​

{
  "total": 42,
  "showing": 20,
  "hasMore": true,
  "elements": [...]
}

Elementos web incluem: tagName, type, id, className, textContent, value, placeholder, href, ariaLabel, role, cssSelector, isInViewport

Elementos móveis incluem: Múltiplas estratégias de localização (accessibility ID, resource ID, XPath, UiAutomator/predicates), tipo de elemento, texto e, opcionalmente, limites

Notas​

  • Web: Usa um script otimizado para detecção rápida de elementos
  • Mobile: Usa análise eficiente da fonte XML da página (2 chamadas HTTP vs 600+ para consultas de elementos)
  • Use paginação (limit e offset) para páginas grandes para reduzir o uso de tokens

Exemplo​

Get all visible elements on the page with their coordinates

Suporte​

  • Navegadores Desktop
  • Aplicativos Móveis

get_accessibility​

Obtém a árvore de acessibilidade da página atual com informações semânticas sobre funções, nomes e estados.

Parâmetros​

ParâmetroTipoObrigatórioPadrãoDescrição
limitnumberNão100Máximo de nós a retornar (0 = ilimitado)
offsetnumberNão0Número de nós a pular (para paginação)
rolesstring[]NãoTodosFiltrar para funções específicas (ex., ["button", "link", "textbox"])
namedOnlybooleanNãotrueRetornar apenas nós com um nome/rótulo

Retorna​

{
  "total": 85,
  "showing": 100,
  "hasMore": false,
  "nodes": [
    { "role": "button", "name": "Submit" },
    { "role": "link", "name": "Home" }
  ]
}

Notas​

  • Apenas navegadores. Para aplicativos móveis, use get_visible_elements em vez disso
  • Útil quando get_visible_elements não retorna os elementos esperados
  • namedOnly: true filtra contêineres anônimos e reduz ruído

Suporte​

  • Navegadores Desktop

Capturas de Tela​

take_screenshot​

Captura uma screenshot da viewport atual.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
outputPathstringNãoCaminho para salvar o arquivo de screenshot. Se omitido, retorna dados base64

Retorna​

Dados de imagem codificados em base64 (PNG ou JPEG) com informações de tamanho.

Notas​

As screenshots são automaticamente otimizadas:

  • Dimensão máxima: 2000px (reduzida se maior)
  • Tamanho máximo do arquivo: 1MB
  • Formato: PNG com compressão máxima, ou JPEG se necessário para atender ao limite de tamanho

Suporte​

  • Navegadores Desktop
  • Aplicativos Móveis

Rolagem​

scroll​

Rola a página para cima ou para baixo por um número especificado de pixels.

Parâmetros​

ParâmetroTipoObrigatórioPadrãoDescrição
directionstringSim-Direção da rolagem: up ou down
pixelsnumberNão500Número de pixels para rolar

Notas​

Apenas navegadores. Para rolagem em dispositivos móveis, use a ferramenta swipe em vez disso.

Suporte​

  • Navegadores Desktop

Gerenciamento de Cookies​

get_cookies​

Obtém cookies da sessão atual.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
namestringNãoNome específico do cookie para recuperar (omita para todos os cookies)

Retorna​

Objetos de cookie com propriedades name, value, domain, path, expiry, secure e httpOnly.

Suporte​

  • Navegadores Desktop

Define um cookie na sessão atual.

Parâmetros​

ParâmetroTipoObrigatórioPadrãoDescrição
namestringSim-Nome do cookie
valuestringSim-Valor do cookie
domainstringNãoAtualDomínio do cookie
pathstringNão/Caminho do cookie
expirynumberNão-Expiração como timestamp Unix (segundos)
securebooleanNão-Flag de segurança
httpOnlybooleanNão-Flag HttpOnly
sameSitestringNão-Atributo SameSite: strict, lax, ou none

Suporte​

  • Navegadores Desktop

delete_cookies​

Exclui cookies da sessão atual.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
namestringNãoNome específico do cookie para excluir (omita para excluir todos)

Suporte​

  • Navegadores Desktop

Gestos de Toque (Mobile)​

tap_element​

Toca em um elemento ou coordenadas da tela.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
selectorstringNão*Seletor para o elemento a tocar
xnumberNão*Coordenada X para toque
ynumberNão*Coordenada Y para toque

*Ou selector ou ambos x e y são necessários.

Suporte​

  • Aplicativos Móveis

swipe​

Realiza um gesto de deslize na direção especificada.

Parâmetros​

ParâmetroTipoObrigatórioPadrãoDescrição
directionstringSim-Direção do deslize: up, down, left, right
durationnumberNão500Duração do deslize em milissegundos (100-5000)
percentnumberNão0.5/0.95Percentual da tela para deslizar (0-1)

Notas​

  • Percentual padrão: 0.5 para deslizes verticais, 0.95 para deslizes horizontais
  • A direção indica o movimento do conteúdo: "deslizar para cima" rola o conteúdo para cima

Exemplo​

Swipe up to scroll down the screen

Suporte​

  • Aplicativos Móveis

drag_and_drop​

Arrasta um elemento para outro elemento ou coordenadas.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
sourceSelectorstringSimSeletor do elemento de origem para arrastar
targetSelectorstringNão*Seletor do elemento de destino para soltar
xnumberNão*Deslocamento X de destino (se não houver targetSelector)
ynumberNão*Deslocamento Y de destino (se não houver targetSelector)
durationnumberNãoPadrão

*Ou targetSelector ou ambos x e y são necessários.

Suporte​

  • Aplicativos Móveis

Ciclo de Vida do Aplicativo (Mobile)​

get_app_state​

Obtém o estado atual de um aplicativo.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
bundleIdstringSimIdentificador do aplicativo (bundle ID para iOS, nome do pacote para Android)

Retorna​

Estado do aplicativo: not installed, not running, running in background (suspended), running in background, ou running in foreground.

Suporte​

  • Aplicativos Móveis

Alternância de Contexto (Aplicativos Híbridos)​

get_contexts​

Lista todos os contextos disponíveis (nativos e webviews).

Parâmetros​

Nenhum

Retorna​

Array de nomes de contexto (ex., ["NATIVE_APP", "WEBVIEW_com.example.app"]).

Suporte​

  • Aplicativos Híbridos Móveis

get_current_context​

Obtém o contexto atualmente ativo.

Parâmetros​

Nenhum

Retorna​

Nome do contexto atual (ex., NATIVE_APP ou WEBVIEW_*).

Suporte​

  • Aplicativos Híbridos Móveis

switch_context​

Alterna entre contextos nativos e webview.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
contextstringSimNome do contexto ou índice (base 1) de get_contexts

Exemplo​

Switch to the WEBVIEW_com.example.app context

Suporte​

  • Aplicativos Híbridos Móveis

Controle de Dispositivo (Mobile)​

rotate_device​

Gira o dispositivo para uma orientação específica.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
orientationstringSimPORTRAIT ou LANDSCAPE

Suporte​

  • Aplicativos Móveis

hide_keyboard​

Oculta o teclado na tela.

Parâmetros​

Nenhum

Suporte​

  • Aplicativos Móveis

get_geolocation​

Obtém as coordenadas GPS atuais.

Parâmetros​

Nenhum

Retorna​

Objeto com latitude, longitude e altitude.

Suporte​

  • Aplicativos Móveis

set_geolocation​

Define as coordenadas GPS do dispositivo.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
latitudenumberSimCoordenada de latitude (-90 a 90)
longitudenumberSimCoordenada de longitude (-180 a 180)
altitudenumberNãoAltitude em metros

Exemplo​

Set geolocation to San Francisco (37.7749, -122.4194)

Suporte​

  • Aplicativos Móveis

Execução de Script​

execute_script​

Executa JavaScript no navegador ou comandos móveis via Appium.

Parâmetros​

ParâmetroTipoObrigatórioDescrição
scriptstringSimCódigo JavaScript (navegador) ou comando móvel (ex., mobile: pressKey)
argsarrayNãoArgumentos para o script

Exemplos de Navegador​

// Get page title
execute_script({ script: "return document.title" })

// Get scroll position
execute_script({ script: "return window.scrollY" })

// Click element by selector
execute_script({ script: "arguments[0].click()", args: ["#myButton"] })

Exemplos para Mobile (Appium)​

// Press back key (Android)
execute_script({ script: "mobile: pressKey", args: [{ keycode: 4 }] })

// Activate app
execute_script({ script: "mobile: activateApp", args: [{ appId: "com.example" }] })

// Terminate app
execute_script({ script: "mobile: terminateApp", args: [{ appId: "com.example" }] })

// Deep link
execute_script({ script: "mobile: deepLink", args: [{ url: "myapp://screen", package: "com.example" }] })

// Shell command (Android)
execute_script({ script: "mobile: shell", args: [{ command: "dumpsys", args: ["battery"] }] })

Códigos de Tecla Comuns do Android​

TeclaCódigo
BACK4
HOME3
ENTER66
MENU82
SEARCH84

Mais Comandos Móveis​

Para uma lista completa dos comandos móveis Appium disponíveis, consulte:

Suporte​

  • Navegadores Desktop
  • Aplicativos Móveis (via comandos móveis Appium)

Welcome! How can I help?

WebdriverIO AI Copilot